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SECTION 



INTRODUCTION 



This document describes the BBN-LISP system currently implemented 
on the SDS 9^0. It is a dialect of LISP 1.5 and the differences 
between IBM 7090 version and this system are described in Appendix 
1 and 2. Principally, this system has been expanded from the 
LISP 1.5 on the 7090 in a number of different ways. BBN-LISP is 
designed to utilize a drum for storage and to provide the user a 
large virtual memory, with a relatively small penalty in speed 
(using special paging techniques described in Bobrow and Murphy 
1967). Secondly, this system has been designed to be a good on- 
line interactive system. Some of the features provided include 
sophisticated debugging facilities with tracing and conditional 
breakpoints, a sophisticated LISP oriented editor within the 
system, and compatible compiler and interpreter. Utilization of 
a uniform error processing through a user accessible function has 
allowed the implementation of a do-what-I-mean feature which can 
correct errors without losing the context of the computation. 
The philosophy of the DWIM feature is described in Teitelman 1969 . 
In addition to the sub-systems described in this manual, a com- 
plete format directed list processing sub-system (FLIP, Teitelman, 
1967) is available within BBN-LISP. There is also an assembler for 
inserting machine code sub-routines within BBN-LISP, and facilities 
for using the CRT display and CALCOMP plotter. 

Although we have tried to be as clear and complete as possible, 
this document is not designed to be an introduction to LISP. 
Therefore, some parts may only be clear to people who have had 
some experience with other LISP systems. A good introduction to 
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LISP has been written by Clark Weissman (1967). Although not 
completely accurate with respect to BBN-LISP, the differences 
are small enough to be mastered by use of this manual and on-line 
interaction. Another useful introduction is given by Berkeley 
(1964) in the collection of Berkeley and Bobrow (1966). 

Changes to this manual will be issued by replacing; sections or 
pages which are faculty and reissuing the index and" table of 
contents at periodic intervals. 
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SECTION II 

USING THE LISP SUBSYSTEM ON THE 9^0 

Call LISP by typing LIS ; the system will respond P; then type _^_; 
when LISP finally responds READY, and types «-, you are talking 
to the LISP supervisor, usually called evalquote . The system 
so obtained contains all of the basic functions and programming 
and debugging aids described in the manual, including the LISP 
compiler and FLIP. Typing SYSGET(T) to evalquote will return you 
to this initial system at any time. Typing control-C will take 
you instantly back to the LISP executive at any time except during 
garbage collection. To get the effect of typing to a Lisp executive 
eval, type E and a space followed by the expression to be evaluated. 
This effect is achieved by the function e described in section 8. 

When typing in to the LISP read function (used by evalquote and 
most other programs), typing a control-Q will clear the input line 
buffer erasing the entire line up to the last carriage return. 
Typing control-A erases the last character typed in, echoing a + 
and the erased character; it will not go beyond the last carriage 
return. Pressing control-R while in the middle of a typein to 

the LISP executive, evalquote , will clear the entire read buffer 
of everything to the last ■*-, and LISP will again type «- . Several 

other control characters are interpreted by the LISP input fork, 
and their functions are summarized in Appendix 3. 
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SECTION III 

DATA TYPES AND THE ORGANIZATION OF VIRTUAL MEMORY 

LISP operates in a 21-bit address space, though only that portion 
currently in use actually exists on the drum. A portion of the 
address space above that actually allocated for structures is 
used for representation of small integers , as described below. 
All data storage is contained within this virtual memory, 
including literal atoms, list structure, arrays and compiled code, 
large integers, floating point numbers, and pushdown list storage. 
This virtual memory is divided into pages of 256 words. References 
to the virtual storage are made via an in-core map which supplies 
the address of the required page if it is in core, or traps to a 
supervisory routine if the page is not in core. This drum super- 
visory routine selects an in-core page, writes it back on the 
drum if it has been changed, and reads the required page from the 
drum. Closed subroutine references to an in-core word through 
the map take approximately 40 microseconds. A reference to a 
word not in core, which must be obtained from the drum, takes up 
to 33 milliseconds, the drum maximum access time. It takes twice 
as long if a page must be written out on the drum before the 
referenced page can be read in. 

Type Determination of Pointers 

The virtual memory is divided into a number of areas as shown in 
Pig. 1. As can be seen from this map of storage, simple arith- 
metic on the address of a pointer will determine its type. We 
chose to allocate storage rather than provide in-core descrip- 
tors of storage areas, because the descriptors take up valuable 
in-core space. 

3.1 
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FIG. 1 MEMORY ALLOCATION IN LISP 
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Literal Atoms 

A literal atom is constructed from any string of characters not 
interpretable as an integer or a floating point number. When a 
string of characters representing a literal atom is read in, a 
search is made to determine if an atom with the same print-name 
has been seen before. If so, a pointer to that atom is used for 
the current atom. If not, a new atom is created.* Thus, as in all 
LISP systems, a literal atom has a unique representation determined 
by its print name. Special syntactic characters can be included 
in print names through the use of the quote mark, ^_ (see the des- 
cription of the function read ) . 

Pour cells (9^0 words) are associated with each literal atom. 
These cells contain pointers to the print-name of the atom, the 
function which it identifies, its top level or global value, and 
its property list. Since atoms occur in only one part of the 

address space, one can tell from a pointer (address) whether 
or not it is pointing to a literal atom. 

Instead of having the four cells associated with each atom on the 
same page, each is put in a separate space in a position compu- 
table from the pointer to the atom. 

Separating value cells and function cells, for example, is useful 
because most users will not use the same name for a global 
variable as they will for a function. Therefore, if the four 
cells were brought in whenever any one was asked for, it is 
likely that the other three cells would never be referenced. Yet, 
they use up room in core which could be used for other storage. 
Similarly, the print-name pointers associated with atoms are 
needed during input and output, but rarely during a computation. 
Therefore, during computation these cells are never in core. 



* and initialized with value NOBIND, property list NIL, function 
definition NIL. o 3 



Car °f a literal atom usually contains the top level binding of 
the atom. If the atom has not yet been set the value cell 
contains the special atom NOBIND. cdr of the atom is a pointer 
to the atom property list, initially NIL. The PNAME cell contains 
a pointer to a packed character table which contains the print- 
name of the atom. The function cell contains NIL until a function 
by that name is defined. It has been defined that car[NIL] and 
cdr[NIL] are NIL, and cannot be changed. These latter two values are 
a significant convenience in programming. 

Numerical Atoms 

Integers 

In LISP, most numerical atoms (numbers) do not have a unique re- 
presentation; that is, a number of different pointers may reference 
numbers with the same value. This implies that for comparison of 
numbers, or for arithmetic operations, the values of the numbers 
must be obtained. The values of floating point numbers and large 
integers are stored in a "full word" space. Pointers to these 
values are used in list structure. 

However, we utilize the fact that not all addresses in the 21 bit 

virtual address space can legitimately appear as pointers in 
list structure. These "illegal" pointers are therefore used in 
the context of list structure to represent "small" integers 
directly, offset by a constant, as indicated in Fig. 1. 

The input format for an integer is any string of digits, option- 
ally preceded by a "+" or "-". Integers must have magnitude less 

2^ 
than 2 . "Small" integers are those of magnitude below approxi- 

-i o 

mately 2 (an assembly parameter). A string of digits followed 
by a "Q" will be interpreted as an octal number. 
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Floating Point Numbers 

Floating point numbers and operations are available in BBN LISP. 
They are stored in two contiguous 2k bit words in standard 9^0 
format, in full word space. When creating an atom with read., 
ratom or pack , LISP will recognize as a floating point number a 

string of digits containing a decimal point. The letter "E" 

x x 
(exponent of 10; i.e. yyExx=yy * 10 ) will also serve to desig- 
nate a floating point number if preceded and followed by one or 
more digits. The following are legal floating point input strings 

5. 5.0 5E0 5E-3 5.2E+6 .3 

The floating point/string conversion, and the floating point 
arithmetic are performed by the POP's and BRS ' s available in the 
9^0 system. Additional information concerning conversion and 
precision is available from the system documentation of these 
routines . 

The atom printing routine (used by prinl , prin2 , prin3 , unpack ) 
will call the system conversion routine when it encounters a 
floating point datum. The output format is controlled by the 
function fltfmtCn] described later. 
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Arrays 



Arrays in BBN LISP have the following format 






Header Block 



Length 



Pointer 



Start 



Rel oc 



Start 



Non-Pointer Area 



Pointer Area 



Relocation Information 



Block Oriqir 



Array Origin 



Typical Array 



The HEADER BLOCK is four cells long and contains: 



Cell: Length of entire block=arravsize + 4-. 

1 Address of first word of protected pointers, 
relative to Array Origin. 

2 Address of first word of rplocation indorsation 
relative to Block Origin. : ' 

3 Used for temporary storage during garbage 
collection. 
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An array may contain both pointer and non-pointer data, separated 
as shown. Pointer data is assumed to be one of the standard LISP 
types, and the pointer data cells in all arrays are used as base 
cells for tracing during garbage collection. The non-pointer 
data, beginning in the fifth cell. of the array, is of unrestricted 
type, and will not be used as trace pointers during garbage 
collection. 

Relocation information contains the relative addresses of cells 
in the array which are to be relocated when the array is used as 
a compiled function, and is placed in core memory. 

Examples: 

1. Compiled code. 

a. Machine instructions and unboxed numeric 
literals are in the non-pointer area. 

b. Other literals and variable name pointers are 
in the pointer area. 

c. Relocation information area addresses all 
machine instructions whose address is within 
the same program, e.g., branch instructions. 

2. Array of lists. 

All data would be in the pointer area; the other 
• areas would be of length 0. 

3. Array of unboxed numbers. 

All data would be in the non-pointer area; the 
other areas would be of length 0. 
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List Structure 

List Structure is created in list space as shown in the memory 
map. Lists can contain pointers to all data types. As can be 
seen from the map, list space and array space grow toward each 
other. The total space available is an assembly parameter. 
The space available in the 4-1-68 LISP system is 144K (K=1024) 
SDS 940 24 bit words, which if used all for list storage would 
provide 72K words; of free storage. 

Shared LISP 

The LISP System as presently implemented contains nearly 90,000 
words of compiled code constituting the miscellaneous functions, 
Editor, Compiler, Break and other service packages. A sharing 
mechanism enables one copy of this code residing on the drum to 
be used by all active users of LISP. This practice results in a 
considerable saving of drum space over that required if each user 
had a separate, private copy of these functions. When a user starts 
a LISP on his console, the virtual memory is set to contain all 
the shared pages which constitute the basic system. In addition, 
roughly 1,000 words of private list storage are also provided. As 
the user adds his own private functions and data to the system, 
private pages are assigned to contain them. Thus a running 
system will typically contain some number of private pages and 
the shared pages of the basic LISP system. 

Fundamental to the proper operation of the sharing mechanism is 
the requirement that no individual user be permitted to change 
the contents of a shared page. Therefore, the shared pages in 
the virtual memory are initially set to be read-only . This means 
that the user can do car of the list structure on a shared page 
but not rplaca . However, circumstances do arise when it is 
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necessary for the user to change his virtual memory in a place 
where a shared page has been mapped. For example, the user may 
set the top level value of an atom contained in the original 
shared system, i.e. change the contents of the value cell. To 
properly handle this situation, the LISP page turning routine 
takes special note of any attempt to store data into a shared 
page and makes a private copy of the page, assigning it to a new 
place on the drum. This nrocedure is invoked automatically and 
is invisible to the user. 

Garbage Collector 

The garbage collector is a routine which serves to locate cells 
no longer in use by the running program and make them again avail- 
able for storage. The various data spaces in LISP 'which may 
need to be garbage collected in this way include lists, arrays 
(and compiled-code) , large integers, floating point numbers, atoms, 
and print-names. 

An automatic garbage collection is usually initiated whenever a 
cell is needed in a space which has become exhausted. This hap- 
pens most frequently when the allocated free list words have be- 
come exhausted by repeated cons es . A garbage collection will also 
be initiated whenever print-name space is exhausted. The garbage 
collection initiated for either of these reasons will reclaim 
lists, numbers, atoms, and print-names. A garbage collection 
initiated when array space is exhausted will collect these spaces, 
and in addition, will compact array space. This means that unused 
arrays will be eliminated, and still-in-use arrays will be moved 
so as to be contiguous. 

When either large integers or floating-point numbers are exhaust- 
ed, a special type garbage collection called number collection 
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is initiated. This operation identifies still-in-use numbers 
by performing a linear sweep over all spaces. This may result 
in the retention of some numbers which are no longer in use. 
Therefore, if a number collection is unsuccessful in obtaining 
free number cells, a regular garbage collection is initiated. 

The user can initiate a regular garbage collection at any time 
via the function reclaim described in Section 10. Note that the 
depletion of atom space will not cause an automatic garbage col- 
lection. Instead, the error ATOM SPACE PULL is generated. 
However, in this case, an explicit reclaim may be successful in 
recovering atoms. 

Allocation of List Space 

Normally, a user will have in use for list structure only a small 
portion of the total space available for this purpose. In order 
to prevent scattering lists over many pages (which ■ increases access 
time), LISP allocates and places on the free list only a portion 
of the total list structure space. A garbage collection will be 
initiated whenever this allocated portion becomes exhausted, 
whether or not additional space is available. After a garbage 
collection, additional pages will be allocated to list space if 
necessary to raise the total number of available free words to 
the minimum, a parameter set by minf s (described in Section 10). 
The two number spaces, atom space, and print name space have 
fixed boundaries, and an error will be generated if additional 
space is needed and none is available. Note that list space 
and array space are allocated from a common area. Array space 
recovered by a garbage collection can be subsequently used by 
list space because array space is compacted. However list space 
is not and cannot reasonably be compacted, so acquiring all of 
LISP's memory for list structure will prevent any further allocation 

of arrays for compiled functions. 
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Shared Areas 

The garbage collector takes special note of the shared areas of 
virtual memory. Specifically, compiled functions and arrays re- 
siding on shared pages are not traced for the purpose of identify- 
ing list structures and numbers to be retained. Instead, a 
separate list, created at the time that the shared system was 
loaded, serves this purpose. This results in a consideratle 
saving of time over what would be required if the garbage collector 
had to trace through all 90,000 words of compiled code in the 
shared system. 

Initially, LISP memory is over half allocated to the shared portion 
of the systems. If a particular user requires more than the re- 
maining space for his program, it is possible to remove portions 
of the shared system using the function flushcode (described in 
Section 22). The portion flushed is automatically available for 
allocation to array space. Atoms in this portion that are now 
no longer used, e.g. function and argument names, can be reclaimed 
via use of the function atomgc described in Section 10. 
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SECTION IV 
FUNCTION TYPES 

There are basically twelve function types in the BBN LISP System. 
These twelve types reflect three characteristics. A 
function may independently have: 

1. its arguments evaluated or unevaluated, 

2. a fixed number of arguments or an indefinite number of 
arguments . 

3. be defined by a LISP expression, 

by permanent system code, or compiled 
machine code. 

Expressions used to define functions must start with either 
LAMBDA, or NLAMBDA; indicating that the arguments of this func- 
tion are to be evaluated, or not evaluated, respectively. 
Following the LAMBDA or NLAMBDA may be a list of atoms (possibly 
empty) or any literal atom (except NIL). If there is a list of aton.s 
each atom in the list is the name of an argument for the function 
defined by the expression. Arguments for the function will be 
evaluated or unevaluated, as dictated by LAMBDA or NLAMBDA, and 
paired with these argument names. This is called "spreading" the 
arguments, and the function is called a spread-LAMBDA or spread- 
NLAMBDA. If an atom follows the LAMBDA or NLAMBDA, this function 
has an indefinite number of arguments.' If it is an NLAMBDA expres- 
sion, then the atom is paired to the list of arguments (unevaluated) 
of the function; that is, to cdr of the form in which this function 
name was car . Such a function is called a "nospread" function. 

If a LAMBDA is followed by an atom, each of its n arguments will 
be evaluated in turn and placed on the parameter push down list. 
The atom following the LAMBDA is bound to the number of arguments 
which have been evaluated. A built-in function arg[m] returns 

4.1 



the value of the mth argument of this function from the push 
down list. For m>n or m^o, arg[m] is undefined. 

Functions defined by expressions can be compiled by the LISP com- 
piler^ as described in the section on the compiler and lap . They 
may also be written directly in machine code using: the ASSEMBLE 
directive of the compiler. Functions created by the compiler , 
whether from S-expressions or ASSEMBLE directives, are referred 
to as compiled functions. Built-in system coded functions 
are called subroutines. To determine the type of any 
function fn, you can use the function fntyp[fn]. The value of 
fntyp is one of the following 12 types: 

SUBR 
SUBR* 
FSUBR 
FSUBR* 

The types in the first column are all defined by expressions. 
The * suffix indicates an indefinite number of arguments (i.e. an 
atom following the LAMBDA or NLAMBDA). The types in the second 
column are compiled versions of the types in the first column, as 
indicated by the prefix C. In the third column are the parallel 
types for built-in subroutines. Functions of types in the first 
two rows evaluate their arguments. The prefix F in the third and 
fourth rows indicates no evaluation of arguments. Thus, for 
example, a CFEXPR* is a compiled form of an NLAMBDA expression with 
an atom following the NLAMBDA. 



EXPR 


CEXPR 


EXPR* 


CEXPR* 


FEXPR 


CFEXPR 


FEXPR* 


CFEXPR* 
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A standard feature of the BBN LISP system is that no error 
occurs if a function is called with too many or too few arguments 
If a function is called with too many arguments, the extra argu- 
ments are evaluated but ignored. If a function is called with 
too few arguments, the unsupplied ones will be delivered as NIL. 
This applies to both built-in and defined functions. 

There is a function progn of an arbitrary number of arguments 
which evaluates the arguments in order and returns the value of 
the last (i.e., it resembles and is an extension of prog2 ) . 

The conditional expression has been generalized so that instead 
of doublets it accepts n+1-tuplets which will be interpreted in 
the following manner: 

(COND 

(PI Ell E12 E13) 
(P2 E21 E22) 

(P3) 

(Pi E4l)) 

will be taken as equivalent to (in LISP 1.5): 

(COND 

(PI (PROGN Ell E12 E13)) 
(P2 (PROGN E21 E22)) 

(P3 P3) 
(P4 E4l) 
(T NIL)) 

This is not exactly true, but only because P3 is not evaluated 
a second time, if the value is needed in the third item in the 
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second conditional expression. Thus, a list in a cond with only 
a predicate and no following expressions causes the value of the 
predicate itself to be returned. Note also that NIL is returned 
if all the predicates have value NIL. No error is invoked. 

LAMBDA and NLAMBDA expressions also have implicit progn * s ; thus 
for example 

(LAMBDA (VI V2) (PI VI) (F2 V2 ) NIL) 

is interpreted as 

(LAMBDA (VI V2) (PROGN (PI VI) (F2 V2 ) NIL)) 

The value of the last expression following LAMBDA (or NLAMBDA) 
is returned as the value of the expression. In this example, 
the function would always return NIL. 
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SECTION V 

PRIMITIVE FUNCTIONS AND PREDICATES 

Primitive Functions 

car[x] car gives the first element of a 

list x, or the left element of a 
dotted pair x. Nominally unde- 
fined for literal atoms, it 
usually gives the top level 
binding (value) of a literal 
atom x. For the usually undefined 
case of a number, its value is 
the number itself. 

cdr[x] car gives the tail of a list (all 

but tne first element). This is 
also the right member of a dotted 
pair. If x is a literal atom, 
cdr[x] gives the property list 
of x. Property lists are usually 
NIL unless modified by the user. 
If x is a number, cdr returns NIL. 

caar[x] = car[car[x]] All 30 combinations of nested 

cars and cdrs up to 4 deep are 
cadr[x] = car[cdr[x]] included in the system. Levels 1, 

2 and 3 are subroutines; 4 is 
cddddr[x] = compiled. All are compiled open 

[cdr[cdr[cdr[cdr[x]]]] by the compller . 
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cons[x;y] cons constructs a dotted pair of 

x and y. If y is a list, x be- 
comes the first element of that 
list. To minimize drum accesses 
the following algorithm is used 
for finding a page on which to 
put the constructeu LISP word. 

cons[x;y] is placed 

1) on the page with y if y is a list and there is room; 
otherwise 

2) on the page with x if x is a list and there is room; 
otherwise 

3) on the same page as the last cons if there is room; 
otherwise 

4) on a page in core if one is available with a specified 
minimum of storage; otherwise 

5) on any page with a specified minimum of storage. 
The specified minimum is presently 20 LISP words in 
both cases. 

The user may effect the operation of cons with the following 
function: 

conspage[x] causes the page on which x re- 

sides to be used for alternative 
3 above instead of the result of 
the previous cons. If x is an 
atom, alternative 4 or 5 will 
be taken. 
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conscount[] Returns the number of conses 

since LISP started up. 

rplacd[x;y] This SUBR places in the 

decrement of the cell 
pointed to by x the pointer y. 
Thus it changes the internal list 
structure physically, as opposed 
to cons which creates a new list 
element. This is the only way 
to get a circular list inside of 
LISP; that is by placing a 
pointer to the beginning of a 
list in a spot at the end of the 
list. Using this function care- 
lessly is one of the few ways to 
really clobber the system. The 
value of rplacd is x* 

rplaca[x;y] This SUBR is similar to rplacd , 

but it replaces the address 
pointer of x with y . The same 
caveats which applied to using 
rplacd apply to rplaca . The 
value of rnlaca is x. Rplaca 
and rplacd of NIL are illegal. 

quote[x] This is a function that prevents 

its argument from being evaluated 
Its value is x itself. 
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cond[c 1 ;c 2 ; . . . ;c k ] 



The conditional function of LISP, 

cond , takes an indefinite number 

of arguments, c, , c~ , . . . c. , called 

clauses. Each clause c_. is a list 

(e-.....e .) of n>l items. The 
— li — ni — 

clauses are considered in sequence 

as follows: the first expression 

e n . of the clause c. is evaluated 
— li — I 

and its value is classified as 
false (equal to NIL) or true (not 
equal to NIL). If the value of 
e, . is true , the expressions 
e_p....e . that follow in clause 
c_. are evaluated in sequence, and 
the value of the conditional is 



the value of e 



— ni 



the last ex- 



pression in the clause. In par- 
ticular, if n=l, i.e., if there is 
only one expression in the clause 
c. , the value of the conditional 
is the value of e, . . 

If e , . is false, then the remainder 
of clause c. is ignored, and the 
next clause c_.+l is considered. If 
no e,. is true for any clause, the 
value of the conditional expression 
is NIL. 

This conditional expression form 
gives the same value as LISP 1.5 
for clauses of exactly two items 
but allows additional flexibility. 
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selectq[x;y 1 ;y 2 ;. . . ;y n ;z] 



This very useful function is used 
to select a sequence of instruc- 
tions based on the value of its 
first argument x. Each of the 
v_. is a list of the form 

( -i -li -2i* "-ki ) 



where s_. is the selection key. 



If s_. is an atom the value of x 
is tested to see if it is ejq to 
s_. (not evaluated). If so, the 



expressions e_, . , . . .e, . are eval- 



uated in sequence, and the value 
of the selectq is the value of 
the last expression evaluated, 



If s_. is a list, and if any ele- 
ment of s_. is ec[ to the value of 
x 
in turn as above. 



, then e, . to e, . are evaluated 
' — li — ki 



If y. is not selected in one of 
the two ways described then 
v_. +1 is tested, etc. until all 
the y_ f s have been tested. If 
none is selected, the value of 
the selectq is the value of z. 
z must be present. 
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An example of the form of a 
selectq is : 
(SELECTQ (CAR X) 

(Q (PRINT F00) (FIE X)) 

((A E I U) (VOWEL X)) 

(Y (TRY -AGAIN X)) 

(COND((NULL X)NIL) 

(T (QUOTE STOP)))) 
which has 3 cases, Q,(A E I U) 
and Y, and a default condition 
which is a cond . 

selectq compiles open, and is 
therefore very fast; however it 
will not work for lists, large 
integers or floating point num- 
bers since it uses a 24 bit open 
compare (an open eq). 



progl[x 1 ;x 2 ;. . . ;x ] 



This function evaluates its 
arguments in order, that is, x-i 
then Xp etc. It returns the 
value of its first argument x... 



prog2[x;y] 



Evaluates x, then y and returns 



progn[x;y;. . . ;z] 



progn evaluates each of its 
arguments in sequence, and re- 
turns the value of its last 
argument as its value. It is an 
extension of prog2 . 
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rpt[n;form] 



Evaluates the expression form 
n times. Returns the value of 
the last evaluation. 



prog[args;e 1 ;e 2 ;. . .£ n ] 



This feature allows the user to 
write an ALGOL-like program con- 
taining LISP statements to be 
executed and is identical to the 
prog in LISP 1.5. The first 
argument is a list of program 
variables. The rest is a se- 
quence of (non-atomic) state- 
ments (expressions), and atomic 
symbols used as labels for trans- 
fer points. The value of a prog 
is determined by the function 
return . If no return is exe- 
cuted, the value of the prog is 
not guaranteed, but will not give 
an error, if flow of control 
"falls off the end". 



go[x] 



go is the function used to cause 
a transfer in prog . (GO A) will 
cause the program to continue at 
the label A. A go can be used at 
any level in a prog . If a go is 
executed in an interpreted function 
which is not a prog , it will be 
executed in the last interpreted 
prog entered. 
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return[x] A return is the normal end of a 

prog . Its argument is evaluated 
and is the value of the prog in 
which it appears. If a return 
is executed in an interpreted 
function which is not a prog, 
the return will be executed in 
the last interpreted prog entered 

set[x;y] This function sets the atom which 

is the value of x, to the value 
of y, and returns the value of v_. 

setq[x;y] This FSUBR is identical to set , 

except that the first argument 
is not evaluated. 
Example: If the value x is c_, 
and the value of v_ is b, then 
set [x;y] would result in £ 
having value b, and b returned. 
setq[x;y] would result in x 
having value b, and b returned. 
In both cases, the value of y 
is unaffected. 

setqq[x;y] Identical to setq except that 

neither argument is evaluated. 
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Predicates and Logical Connectives 

atomCx] atom[x]=T if x is an atom; NIL 

otherwise. 

arraypCx] is T if x is an array; NIL 

otherwise. 

listpCx] is T if x is a nonatomic list- 

structure, i.e., created 
by one or more CONSes NIL 
otherwise. Since arrays are 
not atoms, and will fail an atom 
test, listp should be used to 
distinguish bona fide list 
structure from atoms, numbers, 
arrays, et al. 

nlistp[x] not[listp[x]] 

eq[x;y] The value of e£ is T if x and y 

are pointers to the same structure 
in memory, and NIL otherwise. 
eq is compiled open by the com- 
piler as a 24 bit compare of 
pointers. Its value is not 
guaranteed T for equal numbers 
which are not small integers. 
See eqp . 
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eqp[x;y] The value of eqp is T if x and v_ 

are pointers to the same structure 
in memory, or if x and v_ are num- 
bers and have the same value. Its 
value is NIL otherwise. 

neq[x:y] The value of this function is T 

if x is not ec(_ to v_, and NIL 
otherwise. 

nill[] Defined as (LAMBDA NIL NIL) 

null[x] eq[x;NIL] 

equal [x;y] The value of this function is T 

if x and v_ are isomorphic, that 
is, x and y_ print identically; 
the value of equal is NIL 
otherwise. 

and[x, ;...x , ] This function is an FSUBR and 

can take an indefinite number 
of arguments (including 0). Its 
value is the value of its last 
argument if all of its arguments 
have non-null value, otherwise 
NIL. and[]=T. Arguments past 
the first null argument are not 
evaluated. 
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orO^. . .x n ,] 



not[x] 
memb[x;y] 



This function is also an FSUBR 
and can take an indefinite number 
of arguments (including 0). Its 
value is that of the first argu- 
ment whose value is non-null, 
otherwise NIL. or[]=NIL. Argu- 
ments past the first non-null 
arguments are not evaluated. 

Same as null; that is, eq[x;NIL]. 

This function determines if x is 
a member of list y, i.e. if there 
is an element of y eq to x. If 
so it returns the portion of the 
list starting with that element. 
If not it returns NIL. 



member[x;y] 



Identical to memb except that it 
uses equal instead of eq to check 
membership of x in y. 



intersection [x;y] 



This function returns with a list 
whose elements are members of 
both lists x and y. 



union[x;y ] 



This function is entered with two 
lists. It returns with a list 
consisting of all elements 
included on either of the two 
original lists. If the same 
item is a member of both original 
lists, it is included only once 
on the new list. It is more effi- 
cient to make x be the shorter list. 
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SECTION VI 



LIST MANIPULATION AND CONCATENATION 



iist[xjj. . -;x n >] 



niistCx^^;.. . ,x n , J 



append[x;y] 



nconc£u;v] 



nconcl[lst;x] 



The value of list is a list of 
the values of its arguments. 

Returns a list of the value of 
all arguments (same as LIST), 
but deletes all NIL's at the end 
of this list. Example: 
(NLIST T T NIL T NIL NIL) - 
(T T NIL T) 

This function copies the top 
level of list x and appends list 
v_ to this copy. The value is 
the combined list. If x is NIL, 
it returns v_. 

This function is similar to 
append in effect, but it causes 
this effect by actually modifying 
the list structure x, and making 
the last element in the list x 
point to the list y . The value 
of nconc is a pointer to the first 
list x, but since this first list 
has now been modified, it is a 
pointer to the concatenated list. 
If x is NIL, it returns y_ itself. 

performs nconc[lst;list[x]] . The 
cons will be on the same page as 1st. 
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tconc[x;p] This function provides an effi- 

cient way for placing an item x 
at the end of a list. This list 
is the first item on p, that is, 
car[p]; cdr[p] is a pointer to 
the last element in this list; x 
is placed on the end of the list 
by modifying this structure, and 
x is placed on the list as an 
item. The effect of this function 
is equivalent to 

nconc[car[p]; list[x]], with cdr[p] 
updated to point to the last ele- 
ment of the modified list. 

lconc[x;p] This function is similar to tconc , 

except that in this case x is a 
list. An entire list will be 
tacked on the end of car[p], and 
cdr[p] will be adjusted to be a 
pointer to the last element of 
this new combined list. Both 
tconc and lconc work correctly 
given null arguments. 

attach[x;y] This function attaches the element 

x on the front of the list v_ by 
doing an rplaca and an rplacd . 
This will not work correctly if 
v_ is an atom. Thus it is similar 
to cons , except that it modifies 
the contents of the first element 
of the non-null list y. 
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remove [x;l] 



dremove[x; 1] 



The function remove removes all 
occurrences of x from list 1, 
giving a copy of 1 with all ele- 
ments equal to x removed. 

This function is identical to 
remove , but actually modifies 
the list 1 when removing x, and 
thus does not use any additional 
storage. 



copy[x] 



This function makes a copy of the 
list x» The value of copy is the 
(location of the) copied list. All 
levels of x are copied. 



reverse [1] 



dreverse[l] 



This is a function to reverse the 
top level of a list. Thus, using 
reverse on 
(A B (CD)) gives ( (C D) B A) 

Identical to reverse but dreverse 
destroys the list 1_ while reversing 
by modifying pointers, and thus 
does not use any additional 
storage. 



subst[x;y ;z] 



This function gives the result of 
substituting the S-expression x 
for all occurrences of the 
S-expression v_ in the S-expression 
z. Substitution occurs whenever 
y_ is equal to ear of some sub- 
expression of z or when v_ is 
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subst[x;y;z] (cont.) 



both atomic and eq to cdr of 
some subexpression of z_. P'or 
example: 



subst[A;B;(C B (X . B))] gives 
(C A (X . A)) 

subst[A;(B C);((B C) D B C)] gives 
(A D B C), not (A D . A) 

The value of subst is a copy of 
z_ with the appropriate changes. 



dsubst[x;y ;z] 



Identical to subst s but physically 
inserts a copy of x for y in z, 
thus changing the list structure 
z itself. 



sublis[x;y] 



Here x is a list of pairs: 
((u 1 .v 1 ) (u 2 .v 2 ) ... (%- v n )) 

with each u atomic. 

The value of sublis[x;y] is the 
result of substituting each v 
for the corresponding u in v_. 
Copies the structure v_ with 
changes. 
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lsublis[x;y] x is a list of pairs as for 

sublis , except that the v. are 

substituted as segments of a list, 

not as items. For example, 

sublis[((A B C)); (X AY)] = (X (B C) Y) 

but 

lsublis[((A B C));(X A Y)] = (X B C Y). 

Note also that 

lsublis[((A)); (X A Y)] = (X Y) 

lsublis is destructive: it 
physically changes the list 
structure of y itself. 
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subpair[x;y;z ;fi] 



Similar to sub lis , except that 
elements on y are substituted for 
corresponding atoms on ^ in z_. 
New structure is created only if 
needed, or if fl=T. 



last[x] 



nth[x;n] 



This function has as its value a 
pointer to the last cell in the 
list x, and returns NIL if x is 
an atom. i.e. if x=(A B C) then 
last [x] = (C) 

The arguments of nth are a list x 
and a positive integer n. Its 
value is a list whose first ele- 
ment is the nth element of list 
x. Thus if n = 1, it returns 
the list x itself. If n = 2, 
it returns cdr[x]. If n = 3, 
it returns cddr[x], etc. 
If n = it returns cons [NIL, x]. 



length[x] 



This function has as a value the 
length of the list x. If x is 
an atom, it returns 0. 



count[x] 



Returns the number of LISP words 
in the list structure x. Returns 
if x is an atom. 
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ldiff[x;y;z] 



y is a tail of x> i.e., the result 
of applying some number of CDRs to 
x ldiff[x;y] gives a list of all 
elements in x but not in y, i.e., 
the list diff erence of x and v_. 
Thus (LDIFP X (NTH X (ADD1 M))) 
gives the first M elements of X, 
(LDIFF X (MEMBER (QUOTE F00) X)) 
gives all elements in X up to the 
first F00. 



If z is not NIL the value of ldiff 
is effectively 

nconc[z;ldiff [x;y]] , i.e. the list 
difference is added at the end of z 



editnth[x;n] 



similar to the function nth except 
n may be positive or negative. If 
n is positive, car of value is nth 
element of x. If n is negative, 
car of value is nth element of x 
counting from the end. i.e., 
editnth [x;-l] = last[x]. If n is 
too large (or too small), editnth 
generates an error. Note that 
nth does not. 



li[n;x] 



ri[m;n;x] 

bi[m;n;x] 

lo[n;x] 

ro[n;x] 

bo[n;x] 



equivalent to executing the edit 
command (LI N) when x is the current 
level list. 



equivalent to corresponding edit 
command 

6.7 



makelist [n;m] makes a list of length m consisting 

of the contents of cells n, . . . n+m-1. 

For example, if F00 is an array 

pointer, 

(MAKELIST (PLUS (LOC F00) 4) 3) 

is a list consisting of the first 

three elements in the array F00. 



6.8 



SECTION VII 



PROPERTY LIST FUNCTIONS 



put[x;y ;z] 



remprop[x;y] 



This function puts on the pro- 
perty list of x, the label y 
followed by the property z. The 
current value of z_ replaces any 
previous value of z with label v_ 
on this property list. Its value 
is z_. 

This function rem oves all occur- 
rences of the prop erty with label 
y from the property list of x. 



prop[x;y;u] 



changeprop [x ; propl ; prop2 ] 



The function prop searches the 
list x for an item that is equal 
to y. If such an element is 
found, the value of prop is the 
rest of the list beginning 
immediately after that element. 
Otherwise, the value is u[], 
where u is a function of no argu- 
ments. Its effect is similar to 
memb and member , and they are 
more efficient when usable. 

Changes name of property propl 
to prop 2 , on atom x, (does not 
affect the value of the property) 
Value is x. If propl not found, 
value is NIL. 
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get[x;y] This function gets from the list 

x the item after the atom y on 
list x. If y is not on the list 
x, this function returns NIL. For 
example, get[(A B C D);B] = C. 

getp[x;y] This function get s the property 

with label v_ from the property 
list of x. 

NOTE: Both getp and get may be 
used on property lists. However, 
since getp searches a list two at 
a time, the latter allows one to 
have the same object as both a 
property and a value. e.g., if 
the property list of x is 
(PR0P1 A PR0P2 B A C) 

then get[x;A] = PR0P2, 
but getp[x;A] = C. 

getl[x;y] y is a list of properties, getl 

searches the property list of x, 
two at a time, and returns the 
property list as of the first 
property on v_ tnat it finds, e.g., 
with above property list, 
getl[x;(PR0P2 PR0P3) >(PR0P2 BAG) 

deflist[x;p] This function is used to put 

items on property lists. Its 
first argument x is a list of 
two element lists. The first of 
each is a name. The second ele- 
ment is the value to be stored 
after the property jd on the pro- 
perty list of the name. The 
second argument p is the property 
that is to be used. 
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add[x;y;z] This function adds the value z to 

the list appearing under the 
property v_ on the atom x. If x 
does not have a property y 3 the 
effect is the same as 
put[x;y;list[z]]. 

assoc[x;a] If a is a list of dotted pairs, 

then assoc will produce the first 
pair whose first item is eq to x. If 
such an item is not found, assoc 
will return NIL. 

sassoc[x;y ;u] The function sassoc searches y, 

which is a list of dotted pairs, 
for a pair whose first element is 
equal to x« i If such a pair is 
found, the value of sassoc is this 
pair. 

Otherwise, the function u of no 
no arguments, if given, is taken 
as the value of sassoc . Otherwise, 
its value is NIL. 

Note: Many atoms in the system already have property lists, usually 
for use by the compiler. Be careful not to clobber their property 
lists by using rplacd. 
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SECTION VIII 



FUNCTION DEFINITION AND EVALUATION 



getd[x] 



putd[x;y] 



This function get s the definition 
of the function whose name is 
the value of x. If x is not a 
defined function, the value of 
getd[x] is NIL; if x is a machine 
code function, the value is a 
number. 

putd places the value of y into 
the function cell of the atom 
which is the value of x. This 
is the basic way of defining 
functions. putd is mnemonic for 
put definition on x. The value of 
putd is the definition (value of 
y). 



putdq[x;y] 



This function is similar to putd , 
but both arguments are considered 
quoted, and its value is x. 



mo vd [ from ; t o ; copy fig ] 



Moves definition of from to to 
i.e., redefines to. If copyflg =T 
a codv of the definition of from 

■ ■— ■■.■r, l —y— ■«_«»«•»_-— 

is used. 
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fntyp[fn] This function returns NIL if 

fn if not the name of a de- 
fined function* or a function defi- 
nition. Otherwise fntyp returns one of 
the following as defined in the 
section on function types: 



EXPR 


CEXPR 


SUBR 


EXPR* 


CEXPR* 


SUBR* 


FEXPR 


CFEXPR 


FSUBR 


FEXPR* 


CFEXPR* 


FSUBR* 



The prefix F indicates unevalu- 
ated arguments i the prefix C in- 
dicates compiled code; and the 
suffix * indicates an indefinite 
number of arguments. 

define[x] The argument of define is a list. 

Each element of the list is it- 
self a list containing two 
or more items . In a two-item 
list, the first item of each ele- 
ment of the list is the name of a 
function to be defined, and the 
second item is the defining 
LAMBDA or NLAMBDA expression. In 
longer lists, the first item 
is again the name of the function 
to be defined. The second is the 
LAMBDA list of variables and the 
remainder of the lists are forms for 
evaluation. As an example, consider 
the following two equivalent 



8.2 



expressions for defining the 
function null . 

1) (NULL (LAMBDA (X) (EQ X NIL))) 

2) (NULL (X) (EQ X NIL)) 
define will generate an error on 
encountering an atom where a 
defining list is expected. 

If dfnflg =T, its normal setting, 
an attempt to redefine a function 
fn will cause define to print the 
message (fn REDEFINED) and to 
save the old definition of fn 
using savedef before redefining 
it. 

Note: define will operate correctly if the function is already 
defined and broken, advised , or broken-in . 



savedef [fn] 



Saves the definition of fn on its 
property list under property 
EXPR, CODE, or SUBR depending on 
its type. If fn is a list, savedef 
operates on each function in the 
list. 



uns a ve de f [ f n ; p rop ] 



Restores the definition of fn 
from prop . If prop is not given, 
unsavedef looks under EXPR, CODE, 
and SUBR, in that order, before 
giving an error. If dfnflg= T, the 
current definition of fn is 
saved using savedef . Thus one can 
use unsavedef to switch back and 
forth between two definitions of 
the same function, keeping one 
on its property list and the 
other in the function cell. 
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defineq [x; . . .z] 



If fn is a list, unsavedef operates 
on each function in the list. 

This FEXPR is closely related to 
define . However, it takes an 
indefinite number of arguments 
which are not evaluated. Each of 
the arguments must be a list, of 
the form described in define . 
Using defineq instead of define 
allows one to eliminate two pairs 
of parentheses in writing func- 
tions to be defined for loading 
with the function load . 

Since defineq calls define , dfnflg 
affects its operation as well as 
that of define. 



eval[x] 



eval evaluates the expression x 
and returns this value. 



evala[x;a] 



This is the regular eval from 
709^ LISP. Its first argument is 
a form which is evaluated by us- 
ing the values obtained from a, 
a list of dotted pairs. That is, 
any variables appearing free in 
x, that also appear on a, will be 
given the value indicated on a. 
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evalr[x;a] 



Same as evala except with list a 
reversed. Used by evala. 



e[x] 



This FEXPR is defined as eval ; 
however, it is shorter and it re- 
moves the necessity for the extra 
pair of parentheses for the list 
of arguments for eval . Thus, 
when typing into evalquote one 
can simply type e followed by 
whatever one would type into eval 
and have it evaluated. 



apply[fn;args] 



nargs[fn] 



apply applies the function fn to 
the arguments args . i.e. the 
arguments of fn, args , are not 
evaluated but given to fn direct- 
ly. 

Returns NIL if fn is not a func- 
tion, and the number of arguments 
of fn if it is. It returns 1 for 
functions of type 
EXPR*, FEXPR*, CEXPR*, CFEXPR*, 
CSUBR* and CFSUBR* . 



arglist[fn] 



fn is either the name of a function 
or its definition. Value of arglist 
is the list of names of the arguments, 
or in the case of a non-spread function, 
the single atom that is the name of 
the argument. By convention, arguments 
to all functions of type SUBR are 
u, v, and w, in that order. For func- 
tions of type SUBR*, FSUBR, FSUBR*, 
or undefined functions, arglist causes 
a helpable error. 
8.5 



arg[n] This function works with a func- 

tion of type EXPR* or CEXPR*. 
It returns argument n of that 
function. It is undefined if 
n<0 or n>m where m is the number 
of arguments bound. 

setarg[n;v] Sets argument n of an EXPR* 

function to v. 
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SECTION IX 
THE LISP EDITOR 



The LISP editor allows rapid, convenient modification of list 
structures. Most often it is used to edit function definitions 
(often while the function itself is running) via the function 
editf, e.g. EDITF(APPEND) . However, it can be used to edit vari- 
ables, via editv , property lists, via editp , or arbitrary ex- 
pressions, via edite . ( Editf , editv and editp all use edite , see 
p. 9.18). It is another important feature which allows good on- 
line interaction in the BBN-LISP system. 

Editor Language Structure 

Let us take a concrete example of a list (not necessarily a func- 
tion definition) to be edited. Suppose we are editing the follow- 
ing incorrect definition of the append function: 

(LAMBDA (X) Y (COND ((NUL X) Z) (T (CONS (CAR) 
(APPEND (CDR X Y)))))) . 

At any given moment, the editor's attention is confined to a 

single list (generally a subcomponent of the original list being 

edited), which it will print when given the command P. To avoid 

printing of confusing detail, sublists of sublists will be printed 
simply as &. Thus: 

*P 
(LAMBDA (X) Y (COND & &)). 

where *■ indicates that this line was typed by the user. 
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Only the list on which attention is currently focused may be 
changed. Commands thus fall naturally into four classes: moving 
around in the list structure; making changes in the current list; 
printing parts of the list being edited; and entering and leaving 
the editor. 

Many commands use the convention that an integer designates a 
sublist of the current list* For example, if an integer alone 
is typed, attention is focused on the designated sublist of the 
current list. 

Thus: 

*2 
*P 
(X) 

The converse command is the number 0, which causes the current 
list to revert to its former state. For example, starting again 
with the list at the beginning of the section: 

*3 P 

Y 
*0 P 

(LAMBDA (X) Y (COND & &)). 

Note the use of several commands on a single line. In BBN LISP, 
a carriage return is printed automatically whenever a right paren- 
thesis is typed which causes the parenthesis level to become a 
zero. Therefore, a non-atomic command is necessarily the last 
command on Its line. No commands on a line are performed until 
the user or the system types a carriage return. 
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In the remaining examples, unless mentioned specifically, it is 
assumed that the state of the edit is that which existed at the 
end of the previous example. As above, lines typed by the user 
are prefixed with an asterisk. 

Attention Commands 



The two fundamental commands for moving around the structure have 

th 
already been mentioned: a positive integer n, to examine the n 

sublist, and 0, to revert to the superlist. If n is a positive 

integer, then -n examines the n sublist of the current list 

starting from the end and counting backwards, i.e. -1 examines 

the last sublist of the current list. 



A more drastic command is f, which clears the editor's memory of 
descent through the structure and reestablishes the top level of 
the entire list structure being edited as current. Thus: 

*4 2 1 t P 
(LAMBDA (X) Y ( COND & &)). 

A command similar to n is (NTH n) which caused the list starting 
with the nth element of the current list to become current. Thus 

*(NTH 3) 
* P 

(Y (COND & &)). 
*0 P 
(LAMBDA (X) Y (COND & &)). 
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(NTH -n.) may also be used, with the expected result: 

*(NTH -3) 
*P + 
((X) Y (COND & &)) 

The command (P e), where e is any S-expression, searches for an 
Instance of e in the current list, and then acts like NTH, so 
that for example: 

*(P Y) 

(Y (COND & &))• 

A more thorough (and time-consuming) search is provided by (F e T) 
which searches through the entire structure. Thus: 

*+(F Z T) 
*P 

(Z) 
*0 P 

((NUL X) Z) 
*0 P 

(COND (& Z) (T &)) 
*0 P 

(LAMBDA (X) Y (COND & &)). 
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One more variation is provided by (F e n), which finds the nth 
occurrence of e anywhere in the structure. The search is done 
in printout order, so for example: 

*+ (F X 1) 
*P 

(X) 
*+ (F X 2) 
*P 

(X) 
*0 P 

(NUL X) 
*+ (F X 3) 
*0 P 

(CDR X Y) 

Both the (F e T) and (Fen) commands will automatically ascend to 
higher level expressions if the structure e is not found in the 
current list. The entire search is done in printout order, 
starting with the current list, and, if e is not found, proceeding 
to those portions of higher level lists that would be printed 
subsequently to the current list. Thus: 

* 4 2 P 

((NUL X) Z) 

*(F XT) 

*P 

(X) 

*(F CONS T) 

*P 

(CONS (CAR) (APPEND &)) 
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*0 p 

(T (CONS & &)) 
*(F NUL T) 
(F NUL T) ? 

The question mark typed after the command in error is the editor's 
all-purpose comment: it simply means something is wrong with the 
indicated command. In this case, it is because the search failed 
to find a NUL following the current position, although of course a 
NUL does appear earlier in the structure. 

Another useful variation of the find command is provided by 
(F e N) , to be distinguished from (F e n), n a number. Here N 
means Next, and the search skips over the first element in the 
current list, and then proceeds exactly the same as (F e T). 
Thus the command (F e 2) will produce the same results as the 
command (F e T) followed by (F e N). The find-next command is 
useful for cycling through a large structure and examining and/or 
changing several instances of the same expression. It is also 
extremely useful in conjunction with edit macros, which are 
explained later. 

For all of the four variants of the F command described, the 
argument e_ need not be a literal S-expression. The symbol &: can 
be used to match any single element of a list; the symbol — to 
match with the rest of any list. Thus in our example, 
(F (NUL &) T) will find (NUL X) and (F (CDR — ) T) will find 
(CDR X Y), as will (F (CDR & &) T), but not (F (CDR &) T). 
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These two special symbols can be useful In finding a particular 
expression which is similar to many others. For example, if 
there are many places in a program where the variable X is set, 
(F SETQ T) may not find the expression you are looking for, nor 
perhaps will (F (SETQ X &) T). It may be necessary to type 
(F (SETQ X (LIST — )) T) to find the correct expression. However, 
the usual technique in this case is to pick out a unique expression 
or atom which occurs just prior to the desired expression and 
then do two F commands. This "homing in" process seems to be more 
convenient than ultra-precise specification of e. 

For all find commands, if e is atomic, it will be the first element 
of the current list after the find command has (successfully) oper- 
ated. If e_ is nonatomic, the corresponding structure will be the 
current list. To insert before or after this expression, or to 
delete or replace it, the command UP, described on p. 9.29, can be 
used to make the current list list be the first element in the next 
higher list. 

The find commands can be used on a list structure that is circular 
through a car chain by appropriately setting the free variable 
maxlevel . This variable determines how "deep" the editor will 
search before abandoning a given structure, where the depth of a 
structure is the number of unpaired left parentheses preceding it 
in a printout. Maxlevel is initially set to 100 . 

An abbreviated form exists for doing the usual find command (F e N). 
Typing F e (with no parentheses) achieves the same effect. After 
the F is typed in the editor expects a next expression to be typed 
in as the search goal. See 9.26 for a more complete explanation. 
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Three facilities are available for saving information relating to 
the current state of the edit and later retrieving it. At any 
stage i , the edit, a mark can be made and later returned to. The 
commands are MARK, which marks the current state for future 
referenda; -«-, which returns to the last mark without destroying 
it; and «-•*-, which returns to the last mark and forgets it. For 
example : 

*+ 2| 2 P 

((NUL X) Z) 

*MARK + (F CONS T) 

*P 

(CONS (CAR) (APPEND &)) 

* + P 

(LAMBDA (X) Y (COND & &)) 

*«-«- p 

((NUL X) Z) 
*«- p 

«- ? 

This last example demonstrates another facet of the error recovery 
mechanism: to avoid further confusion when an error occurs, all 
commands on the line beyond the one which caused the error are 
forgotten. 

Frequently one wants to move or copy a sublist from one place in 
the structure being edited to another. No command for performing, 
this particular operation is provided. However, it is possible to 
set a variable to the current list, with a command (S v) , or to 
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the nth sublist of the current list with (S v n), n positive or 
negative. The 1^ command described below can then be used to treat 
this value exactly as though it had been typed in literally. Thus 

*+ (S EL2 2) 

will result in setting the value of EL2 to the sublist (X). 

Modification commands 

Just as most general text editors contain INSERT, REPLACE, and 
APPEND commands, the LISP editor provides facilities for these 
three basic operations. To insert the S-expressions e^.-.e^ 
before sublist n of the current list, one simply gives the 
command (-n e, . . . ■ e. m ) > thus : 
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*t (F CAR T) 
*P 

(CAR) 
*(-l CRR) 

P 

(CRR CAR) 



To replace the nth sublist with e,...e . one gives the command 
(n e-....e ), for example: 



*+(P NUL T) 
*P 

(NUL X) 
*(1 NULL IS) 
*P 

(NULL IS X) 



To append the elements e. 1 -««e m to the end of the current list, one 



;ives the command (N e, ...e_ m ). 



*(N THIS LIST) 
*P 
(NULL IS X THIS LIST) 



Deletions may be accomplished by using the replace operation with 
no new S-expressions specified: to restore the list we have just 
created to the state in which we presumably want it, we can say: 
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*(5) 
*(4) 
*(2) 
*P 
(NULL X) 

Deletions should generally be made from back to front, since other- 
wise the indices of later sublists will change as earlier ones 
are deleted, e.g. the above sequence of commands given in front 
to back order would have been 



*(2) 
*(3) 
*(3) 



Very often one wants to make a simple change in a list structure, 
without wanting to know exactly how to trace down the structure 
to the point where the emendation is to be made. The command 
(R e, e 2 ) replaces all occurrences of e^ by e p in the current 
list and all its substructure. This is done using a variant of 
subst called dsubst that runs faster, and physically replaces the 
old structure in the list^y a copy of the new structure. For 
example:. 

*+ (R Z Y) 
*4 2 P 
((NUL X) Y) 

A mechanism by which lists saved with the S command may be used, 
is (I c e,, ... e n ) 9 which is equivalent to 
([atom[c]-*-c; T**-eval[c]T eval[e,] . . . eval[e n ]) . 
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If EL2 has been set to (X) as shown above: 

*+ (I (CAR (QUOTE (F))) (CAR EL2) T) 
*P 
(X) 

because the I command is equivalent to (F X T) . 

Structure changing commands 

The commands presented in the last section do not allow convenient 
alteration of the list structure itself, as opposed to components 
thereof. Consider, for example, the list (A B (CD E) F G). We 
can remove the parenthesis around (C D E), which is the third 
sublist, by (LO 3) (this stands for take Left paren Out). This 
produces the list (A B C D E). LO simply deletes all elements of 
the original list beyond the one specified. If we want to preserve 
them, we could say (BO 3) a take Both parentheses Out, which pro- 
duces (A B C D E F G). Conversely, if we want to take the partial 
list beginning at B and subordinate it one level, making 
(A (B (C D E) F G)), we can say (LI 2), i.e. put a Left parenthe- 
sis in before sublist 2 (and a matching right parenthesis at the 
end of the list). Again, if we want the matching right parenthe- 
sis inserted somewhere other than at the end of the list (after 
the F, for example), we can say (BI 2 4), put Both parentheses 
In around elements 2 through 4, which results in the list 
(A (B (C D E) F) G). 

Two other operations of this sort are also possible. If we wanted 
to bring only the D and E up to the level of the A B F G, and 
leave (C) as a sublist, we can use (RI 3 1), namely move the Right 
paren at the end of sublist 3 In to sublist 3 after element 1 
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of sublist 3. This will produce (A B (C) D E F f*). A related 
operation is (RO 3) s which means move the Right parenthesis of 
sublist 3 Out to the end of the list, producing (A B (C D E P G)). 

Finally, if one wants to move a right parenthesis only n art- 
way out, for example to produce (A B (C D E F) G), this can be 
accomplished by (RO 3) followed by (RI 3 4). 



Printing commands 

We have already encountered the command P, which prints the current 
list showing only one level of nesting. To print a selected sub- 
list in the same way without changing the state of the edit, 
(P n) is used: for example, 

* + P 

(LAMBDA (X) Y (COND & &)) 
*(P 2) 

(X). 

Furthermore, one may examine the nth sublist (or, if n=0, the 
current list) to m levels of nesting by using (P n m) . The con- 
vention is that m=3 yields the usual format: several illustrations 
are given below: 

*(P 1) 

& 
*(P 2) 

(LAMBDA & Y &) 

*(P 3) 

(LAMBDA (X) Y (COND & &)) 

*(P 4 2) 

(COND & &) 
*(P 4 4) 

(COND ((NUL X) Z) (T (CONS & &))). 
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Another command which is available for examining the environment 
during editing is (E e), which simply evaluates e and prints its value 
without disturbing the state of the edit. This is done under 
errorset, so that one can actually try to run the function which 
one is editing. It should be mentioned that changes are made as 
soon as they are typed in, so that the state of the definition of 
a function (which is what is usually being edited) is always 
exactly what one expects. Typing E e (without parentheses) also 
causes e to be evaluated. 

The command (E e T) causes the expression e to be evaluated without 
being printed. It is primarily useful for defining macros. 

The command PP causes the current list to be printed in a pretty 

form using printdef , a subordinate function of prettyprint (see 14.14), 

PP is equivalent to the two commands (S F00) (E (PRINTDEF F00) T). 

This completes the discussion of the commands built into the editor. 
The following section on Edit Macros describes ways of augmenting 
this set. It should be emphasized that all user inputs are 
interpreted as edit commands, and have no bearing on any external 
functions. The command (F X T) will not be affected by the 
existence of a user function named F. The work done by the commands 
LI,LO,RI,RO,BI, and BO happen to be carried out by edit functions of 
the same name; but as far as the user is concerned, he is not calling 
these functions when he types (LI 2), but merely giving the 
editor a command which in some mysterious way it carries out. The 
only way the user can call a function explicitly is to use either 
the E or I command, (or to use a macro which uses an E or an I 
command) 
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Edit Macros 



In. editing a set of functions, to make a consistent change in a num- 
ber of places, one must give the same sequence of commands a number of 
times. For example, to replace all occurrences of calls to 
(F00 &) by calls to (FIE & T), (where & stands for any expression), 
one would type 



(F F00 T) 
(1 FIE) 
(N T) 

as many times as the replacement was necessary. To save this 
typing, one can define an edit Macro, called RF for example, by 
typing 

(M RF (F F00 T) (1 FIE) (N T)) 

Then each time you type RF the sequence of commands, following the 
RF in the definition list, will be executed. If RF were made the 
last command in the list, the sequence would be repeated until F00 
could not be found, that is if RF were defined by 
(M RF (F F00 T) (1 FIE) (N. T) RF) 

The simple edit macro described above cannot be given any argu- 
ments, and will always do exactly the same thing. One can also 
define macros which use parameters. For example, to define a 
macro to switch two items in a list, one would type 

(M.(SW)-(A B) (S SW1 A) (S SW2 B) (I B SW1) (I A SW2)) 
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where the list of argument names (A B) immediately follows the 

macro name, SW, which is listed to indicate that SW will always be 
used with arguments. To make this macro, SW, switch items 2 and 7 
in a list, one would type 

(SW 2 7) 

This command would substitute 2 for A, and 7 for B, in the macro 
definition following the argument list (A B); and then execute 
that sequence of commands with the substituted values. In this 
case, the sequence would be 

(S SW1 2) 
(S SW2 7) 
(I 7 SW1) 
(I 2 SW2) 

An example of a macro which calls a function is 

(M (POO) (N FN) (NTH N) (S PIE 1) (I 1 (FN PIE))) 

Thus typing (F00 -1 CADR) would cause the last element in the 
current list to be replaced by CADR of that element by executing 
the following sequence of edit commands: 

(NTH -1) 

(S FIE 1) 

(I 1 (CADR FIE)) 

Note that a macro with no parameters is called by typing an atom 
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(its name); a macro with parameters must be called by using its 
name as the first element of a list, followed by its "arguments" 
which are substituted for the parameters of the macro in its defi- 
nition. A macro with arguments may have a fixed or indefinite 
number of arguments parallel to the PEXPR and FEXPR* function 
types. A macro with a fixed number of arguments, such as SW, has, 
following its name in the macro definition, a parameter list con- 
taining the argument names. The arguments in the call to the 
macro are substituted in the macro definition before executing that 
sequence of editor commands. A macro with an indefinite number of 
arguments is indicated by having an atomic parameter list following 
its name in its definition. In this case, the entire list of 
arguments is substituted for this atom in the macro definition, and 
then the sequence of editor commands is executed. 

All edit macro definitions are kept on a free variable called 
EDITMACROS. New definitions supercede old ones, or the value 
of EDITMACROS itself can be edited to delete, replace, or 
change macro definitions. Purely local macros, i.e., those that 
will not be used after the current editing job, can be defined 
using D, for define, in place of M. These will not be saved on 
EDITMACROS, but their definitions will, temporarily, supercede any 
macros of the same name that appear on EDITMACROS. 

The macro feature allows the user to easily expand the repertoire 
of edit commands, and thus "program" the editor. Note that entirely 
new editing operations can be implemented by defining an appropriate 
function, and then introducing it to the editor's vocabulary via a 
macro which calls the function. For example, if no find feature 
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were provided in the editor, the user could define a function 
FIND, and a macro 

(M F (X Y)(E (FIND X Y) T)) 

for doing the job. 

Using the editor 

As presently interfaced to the outside world, the editor consists 
of a basic function for editing S-expressions, edite, and three 
special NLAMBDA functions for editing values, definitions, and 
property lists, respectively editv, editf , and editp. Thus, 

*EDITF( APPEND) 
EDIT 

would be used to begin the edit which has been used as the example. 
When editing is complete, OK will cause edite to exit with 
the edited list as value. The three interface functions all re- 
turn as value the atom being edited, and place the edited 
expression in the appropriate place. 

The editor can be used as a subroutine by giving edite a list 
of commands to be executed as its second argument. Each command 
will be executed and, if no errors occur, the edited list returned 
after their completion. Otherwise, edite goes into normal on-line 
mode and waits for user .commands. Editf , editv , and editp all 
accept an indefinite number of commands to be interpreted in this 
fashion: they are each non-spread NLAMBDA type functions, where 
CAR of their argument is the function/property list/value to be 
edited, and CDR the (optional) commands to be supplied to EPITE. 

Edite uses editl, which takes the edit push-down list, L, as its 
argument, executes commands until an OK is reached, and then 
returns the new L as its value. 
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The user can also write his ov/n editing programs which directly 
call editcom, the function that does the work in the editor. The 
workings of this function are explained below under Internal 
Organization of Editor . 

Since all input and output commands in the editor specify the file 
as teletype, it is possible to edit a function when input and/or 
output standard files are other than tne teletype. 

A complete example, starting with the erroneous definition given 
at the beginning of Section IX and ending with the correct defini- 
tion of append , is given below. 

+EDITF(APPEND) 

EDIT 
*(P 100) 

(LAMBDA (X) Y (COND ((NUL X) Z) (T (CONS (CAR) (APPEND 
(CDR X Y)))))) 

*(3) 

*(2 (X Y)) 

*P 

(LAMBDA (X Y) (COND & &)) 
*(R NUL NULL) 
*(R Z Y) 
«(F CAR T) 
*(N X) 

*+(F CONS T) 
*3 (RI 2 2) 

(APPEND (CDR X) Y) 
*t(P 100) 

(LAMBDA (X Y) (COND ((NULL X) Y) (T (CONS (CAR X) (APPEND 
(CDR X) Y))))) 
*0K 
APPEND 

■4- 
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In* all fairness, it should be admitted that in this particular 
instance it probably would have been faster to type the function 
in again. However, LISP functions are typically three times as 
big as append and have only one or two errors. It has been found, 
after over a year of use at BBN and Berkeley, that the editor just 
described does materially decrease the amount of time required 
to produce working LISP programs. 

Internal Organization of the Editor 

The work of the editor is done by the function editcom, which 
interprets and executes a single edit command and editcoms which 
takes a list of commands, editl does the reading from the teletype, 
and transmits commands to editcom under errorset protection, until 
an OK command is given. All errors and control-R 1 s are caught by 
this errorset , and cause editl to print a "?". 

Editcom accepts a single command as an argument and uses as free 
variables L, M, and EM which are normally bound in editl . If the 
user wishes to define a function which calls editcom or editcoms. 



directly, these variables should be bound in that function. Their 
interpretation is: 

L is the edit push-down list. It is initialized to Ust of 

the expression being edited. (CAR L) is always the current 
list being examined; (CADR L) is the list you would be examining 
if you gave a command, etc. Each operation which descends 
to a lower structure, such as the F command or a number, 
causes the higher level struct ure(s) to be attached at the 
front of L. Operations which ascend, such as 0, or t, 
take things off the front of L. 

M is a list of marks made by the MARK command. It need not be 

bound if marks are not used. Ttee command MARK simply performs 
(SETQ M (CONS L M) ) , the command * does (SETQ L (CAR M) ) . 



9.20 



EM contains the list of editmacros being used. It is initialized 
to the value of EDITMACROS. M commands change EM and 
EDITMACROS, D commands just change EM. EM is searched when- 
ever an unfamiliar command is encountered. 



When editcom is given a command that it does not recognize, it 

searches EM using assoc on the command, if atomic, or car of the 

command if a list. If the command has been defined as a macro, 

editcom performs as described earlier. Otherwise, editcom 

calls edltde fault , a function of one argument, which is currently 

defined as (LAMBDA (C) (ERROR O). This causes an error 

which is caught by the errorset in editl However, editdefault 

can be redefined by the user. In fact, edit default has been 
redefined to implement some of the operations of the expanded 
editor described below. For example to treat all unrecog- 
nizable forms as expressions to be evaluated ala break , one would 
define editdefault as (LAMBDA (C) (PRINT (EVAL C))). If any 
error occurred in the evaluation, it would still be caught by the 
errorset in editl . Another possibility might be to have editdefault 
search the property list of the indicated command to look for a 
macro definition, or treat the command as a function call with L 
as its argument, etc. 
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A Summary of the Editor Commands 



Atoms 



n>o 
n<o 
n = o 



Makes nth element be current level list 

Makes nth element from end be current level list 

Makes previous level be current level list 



PP 

t 

MARK 



P 



OK 



Prints current level list to depth 3 

fcrettyprints current level list 

Makes current list be the top level list 

Marks this point 

Makes current level be last marked list 

Makes current level be last marked list and forgets mark 

equivalent to (F X N) where X is the next expression 

read, e.g. *F COND 

equivalent to (E X) where X is next expression read, 

e.g. *E (EDITV POO) 

Exit from editor 



Other atoms are given to editdefault . 
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Lists 



(n e, e 2 ,..., e,) n>0 k^O 



Replace element n by the k elements 
e, , . . . , e. . Deletes the rith ele- 
ment if k=0 



(-n e e 2 ,...,e.) n>0 k^l Inserts e^,..., e_ k before nth ele- 
ment 



(N e 15 . . . , e k ) 



Adds e, . . . e, at end of current 
level list 



(S name) 

and 
(S name 0) 



Sets name to current level list 



(S name n) 



(R old new) 



Sets name to nth element, if n>0, 
Sets name to nth element from end 

of list, n<0. 
Gives error if no such element. 
Replaces all occurrences of the 
old item by new in current level 
list 



(P n m) n^O 



Prints element n to depth m 
(current list if n=0) 



(F e) 



Finds e at current level; " &" 
matches any itenv, " — " matches any 
remaining list 



(F e T) 
(F e N) 



Finds e at any level 

Finds next occurrence of e excluding 
first element in current list 



(F e n) n^l 



Finds nth occurrence of e any level 
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(NTH n) n*l 



Makes nth element be first element 
of current list 



n<0 



Makes nth element from the end be 
the first element on the list 



(I command e-,...e.) 



Evaluates e,...e, and then performs 
command as usual. 
Command can be a number, N, R, F, 
etc. If command is not atomic, 
it is evaluated 



(E e) 
(E e T) 
(LO n) 



Evaluates and prints e 
Evaluates e but does not print. 
Removes left paren before element 
n (and removes a right paren at 
end of current list. If there are 
no more right parens at end of 
list, elements left hanging 
"drop off"). 



(LI n) 



Inserts left paren before element 
n, (and a corresponding right paren 
at the end of the list). 



(RO n) 



Removes right paren after element 
n. It moves it to the end of the 
current list. 



(RI n m) 



Inserts right paren in element n 
after mth subelement of element n. In 
element n, it moves a right paren from 
the end of element n which must have 
more than m elements. 
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(BO n) 



Removes both left and right parens 
around element n 



(BI n m) 



Inserts both left and right parens, 
making a sublist at position n 
containing elements n to m inclusive 



All of the above six commands, LO, LI, RO, RI, BO, and BI, accept 
positive or negative numbers as arguments. Negative numbers are 
positions relative to the end of the list. 



(M name c., c 2 



°n> 



Defines name , as an Edit Macro 

equivalent to the sequence of 

commands c n , c , ... c , if name 
—1' —2' — n' 

is atomic, and c_ 2 , ... c with 
substitution of arguments for 
parameters when car [name] appears 
as car of a non-atomic command, and 
name is listed in definition. 



(D name c, Cp ... c ) 



Same as M but effect is temporary - 
confined to this call to edite. 



All other lists are given to editdefault. 
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The Expanded Editor 

Supereditflg 

All of the commands described below are available to the user 
whether or not he sets SUPEREDITFLG to T. With SUPEREDITFLG = T, 
any unrecognized commands will be interpreted as (F command N), (*) 
e.g., (CAR X) is equivalent to (F (CAR X) N). With SUPEREDITFLG = NIL, 
these will, of course, cause an error and the editor will print 
a ?. SUPEREDITFLG can be set to T by using the edit macro bell 

(control G), which flips the state of SUPEREDITFLG and prints its 
new value, or by setting it yourself. 

New F Command 



If the user wishes to operate with SUPEREDITFLG = NIL, or for 
those cases where he wants to locate an expression which would 
normally be recognized as a command, and therefore not b e searched 
for, e.g., P, PP, or a number, the following abbreviated form of 
the F command is available: 

F expression 

will cause expression to be found a la SUPEREDITFLG. Note that 
in this form, the user is giving two "commands" to the editor to 
express a single find operation. The effect is the same as 
though SUPEREDITFLG were set to T only for the next input after 
the F, except that no attempt will be made to treat this input 
as an edit command so that F P, or F 6 will work. 



(*) (F command) is done first (using MEMB), so that if LOOP is 
a PROG label, and that PROG is the current level list, LOOP will 
find the label before looking for any nested GO'S. 
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In the discussion that follows, the examples in the text 
assumes SUPEREDITFLG is set to T. The identical operation 
can be performed with SUPEREDITFLG = NIL if the user substitutes 
F expression for expression wherever a find command is intended. 



The Location Routine 

All of the commands in the expanded editor use a single routine 
for locating the place at which the operation is to begin. In 

this discussion, the symbol % will be used to mean a location 
specification. @ has no meaning to the editor , it is purely a 
notational device. The following options may appear a_t @ . 

1. @ .NIL Effectively a NOP. 

2. % atomic The single command % is executed, e.g., 

% = 3 means operation is to begin at 3rd 
element of current list. i = COND means 
operation is to begin at the next COND, 
i.e., the command COND is executed, and the 
next occurrence of COND is found. 

3. % a list Each of the commands in @ is executed and 

the operation begins after the last one is 
successfully complete, e.g., (COND 3) locates 
the second clause in the next COND (the COND 
itself counts as 1). Note, (CAR X) will 
first find CAR and then find X. It is 
equivalent to ((P CAR N) (F X N)), or to 
(F CAR F X). To find (CAR X) itself, use 
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((CAR X)) which is equivalent to 
((F (CAR X) N)), or (P (CAR X)). 

If the execution of the commands in @ is 
not successful, i.e., an error occurs, the 
location tries again from the point that the 
error occurs until it is successful or until 
no progress is being made. Thus, if the 
first COND beyond the current point contained 
only one clause, @ = (COND 3) would then 
look for the next COND after that, etc. At 
the point that there were no more CONDs 
remaining in the list being edited, the 
locator routine would give up. If this 
occurs, the status of the edit reverts to 
its state when the locater was entered. 

The locater routine can be called by the user directly via the 
macro LC. To locate @, type (LC . @), e.g., to locate (COND 3) 
type (LC COND 3). To locate COND, type (LC COND), 
i.e., g = (COND) which is equivalent to @ = COND, since both 
consist of the single command COND. 
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UP 



Another command used by all of the commands described below Is UP. 
The effect of UP Is the following: 

1. If the result of typing P Is an element in your list structure, 
then after UP, that element will be the first element in your 
current list. 

2. If the result of typing P is a tail in your list structure, 
then UP has no effect. 

Examples: 

Your current level list structure is (COND ((NULL X) (RETURN Y))). 

1. * 1 P UP P 
COND 

(COND ((NULL X) (RETURN Y))) 

2. *-l P UP P 

((NULL X) (RETURN Y)) 
(((NULL X) (RETURN Y))) 

3. *NULL P UP P 
(NULL X) 

((NULL X) (RETURN Y)) 

4. * X P UP P 
(X) 

(X) 
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5. *(NTH 2) P UP P 

(((NULL X) (RETURN Y))) 
(((NULL X) (RETURN Y))) 

This explanation covers the HOW and WHAT of UP, the WHY will 
become clear in the explanation of the commands given below. 

Insertion, Replacement, and Deletion Commands 

The basic editor provides commands for inserting elements before 
a certain position in the current level list, and for replacing 
or deleting specified positions in the current level list. 
However, since the operation is tied up with the location, it is 
impossible for the user to give single commands for deleting the 
last element in the list, inserting a certain structure before 
the second element from the end of the current list, etc. The 
following three commands are more general than the basic editor 1 s 
commands, and do provide such a capability. In the description, 
% indicates a location operation, and expr a sequence of expres- 
sions (possibly null). 

1. (B @ expr) locates @,does an UP, and inserts 

expression Before current point, 
i.e., effectively does (-1 expr). 

2. (A @ expr) locates @, does an UP, and inserts 

expression after this point, i.e., 
does either a (-2 expr) or (N expr) 
whichever is appropriate. 

3. (: @ expr) locates @, does an UP, and replaces 

first element with expr. If expr is 
null, it deletes the first element. 

All three commands leave edit position as of locating @ but do 
not change marks. 
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Examples: Current list is (COND ((NULL X) (RETURN Y))) 

1. *(A NULL (PRINT Y)) 
P 

((NULL X) (PRINT Y) (RETURN Y)) 

2. *(: X (CDR X)) 
P 

(NULL (CDR X)) 

Current list is (COND ((NULL X) (RETURN Y)) 

((NULL (SETQ Z (CDR Z))) (GO LP)) 
(T (ERROR)) 

3. *(: T) P 

(COND ((NULL X) (RETURN Y)) ((NULL &) (GO LP))) 

4. * (B GO (PRINT Y) (PRINT X)) P 
((PRINT Y) (PRINT X) (GO LP)) 

5. *(: (NULL NULL) (EQ X Z)) P 
((EQ X Z) (GO LP)) 

6. *(: (3 1) (EQ X Z)) P 
((EQ X Z) (GO LP)) 

7. *(B -1 ((EQ X Z) (GO LP1)) P 
(((EQ X Z) (GO LP1)) (T (ERROR))) 

An exception to the above procedure occurs when the expression 
is to be replaced by a function . In this case, UP is not per- 
formed. For example: 

(: CAR X) will replace (CAR &) by X; (: CAR CDR) will 
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replace just CAR by CDR; (: CAR (CDR X)) will replace 
(CAR &) by (CAR X).. 

Note that (: NIL) or just (:) deletes the current level list. 

(: NIL expr) replaces it with expr . Similarly (A NIL expr) 

and (B NIL expr) insert expr , respectively, after and before current 

level list. 



Switcning and Moving Expressions 

Note: The SW and MV commands described below require two 
location specifications. In both cases, the location of 
the second position is begun at the same point that the 
first location started; i.e., the commands save the state 
of the edit upon entering, and return to that position for 
the second location. However, a MARK is performed after 
the first location so that by making < — be the first 
command for the second location, the user can begin that 
locating process where the first one left off. 



The Switch Command 

(SW @1 . @2) @1 is located, an UP performed, SW1 

set to the first element, and the 
current position saved. Then @2 is 
located, an UP performed, SW2 set to 
the first element, which is then 
replaced by a copy of SW1. 
A copy of SW2 then replaces the 
original SW1. SW leaves marks and 
position unchanged. 
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Examples: 
(SW -1 2) 



The last element In the list is 
switched with the second element. 



(SW 2 3 1) 



(SW RETURN GO) 



switches second element with first 
element of third element in current 
level list. 

The first (RETURN — ) is switched with 
the first (GO — ). Note that they may 
be on entirely different levels. How- 
ever, one should not be inside of the 
other. 



The Move Command 



(MV 01 C . 02) 



Examples: 



(MV RETURN B -1) 



@1 located, an UP performed, the vari- 
able MV1 set to the first element. @2 is 
then located and the operation indicated 
by C is performed. Then the former occurrence 
of MV1 is deleted. MV leaves marks and 
position unchanged. 



will find the first RETURN expression 
and insert it before the last element 



in the current level list. 



(MV (COND SETQ) : GO) 



finds the first SETQ after the first 
COND, and re places the first GO by that 
SETQ. 
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(MV -3 N + 3) 



takes the third element from the end of 
the current list and attaches it at the 
end of the third expression from the top. 



The Extract Command 

This command is designed to replace a certain expression by one 
of its subexpressions. 



(XTR @1 . g2) 



locates 61, does an UP, saves the posi- 
tion, locates @2 (beginning from the 
point §1 left off), does an UP, sets 
the variable XTR1 to the first expres- 
sion, returns to saved position, and 
replaced first expression by XTR1. XTR 
leaves marks and position unchanged. 



Examples : 



(XTR COND SETQ) 
(XTR COND 2 2) 



replaces first COND by first SETQ, 
replaces first COND by second expression 
in its first clause. 



Note: While the XTR command is designed to replace an 
expression by a subexpression, there is no check made to 
see that the result of locating @2 is in fact inside of §1. 

The Embed Command 

The embed command is designed to replace a particular expression 
by a larger expression containing it. 
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(MBD @ X) @ is located, an UP performed, and the 

first expression replaced by the result 

of substituting it in X for the variable *. 
MBD leaves current position as the new 

super-expression, with an extra MARK which 
is set to the original position when MBD 
was entered. 

(MBD @ XI ... Xn) (XI must be atomic) 

Same as (MBD @ (XI ... Xn *)) 

Examples: 

(MBD NIL (COND ((NULL X) *))) 

replaces current-expression by 

(COND ((NULL X) current-expression))) 

(MBD 2 QUOTE) quotes second expression 

(MBD -1 SETQ X) replaces last expression by 

(SETQ X last-expression) . 

Miscellaneous Commands 

(* N) moves editor to current expression plus or 

minus N, i.e., (* 1) equivalent to the 
command UP followed by 2. If the current 
expression is the 4th, (* -1) is equivalent 
to followed by 3. 

BK for back, same as (* -1). 

NX for next, same as (* 1) 

DELETE same as ( : ) 

? (P 100) 
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TTY 



calls edltl and sets L to new value, i.e. 
accepts commands from user. Useful for 
functions that call editor as subroutine, 
e.g. breakin[FOO (AFTER COND SETQ TTY)] 
allows the user to interact before the 
break is inserted. 



STOP 



(SECOND . X) 
(THIRD . X) 



used in connection with TTY command, same 
as OK command given to next higher call to 
editl, i.e. aborts the editing operation 
of the subroutine that was calling the 
editor. 

locates SECOND X, no change if not found, 
as above 



(ORR XI X2 ... Xn) 



(## . commands) 



(LCL . commands) 



The sequence of commands XI is executed. 

If successful, ORR returns. If not, the 

state of the edit is restored to its original 

state and X2 executed, etc. This is a way 

of executing commands conditionally* e.g., the 
command SECOND is defined as (ORR ((LC . X)(LC . J) ) ) 

sequence of commands is executed for value , 
not effect, i.e., (## 2 -1) has as its value 
the last element in the second element of 
the current list. ## does not change the 
state of the edit. ## is also an nlambda- 

nospread function. 

Commands ai'e executed locally, i.e., find 
commands will not be allowed to search beyond 
current list. 
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(IF form) 



(LP . commands) 



If the value of form is NIL, an error is 

generated. Designed for use with ORR and 

locating routine. For example, 

(ADD1 (IF (NUMBERP . (## 2))) 

as a location specification will find the 

first ADD1 followed by a number. IF does not 
change state of the edit. 

sequence of commands is executed repeatedly 
Until an error occurs, e.g., 
(LP PRINT (N T)) will attach a T at the end 
of all PRINTS. LP will print number of 
successful iterations. 



(LPQ . commands) 



same as LP but does not print number of 
iterations . 



Note: the routines that handle A, B, :, and MB D commands make 
special checks (of a flag) so that the user can do commands like 
(B PRINT (PRIN1 ZOT))) or (LP (MBD X LIST)) without getting in 
an infinite loop. 



(<- X) 



does repeated commands until finds a 
position for which first element is X, e.g., 
(«- COND) takes you up to the COND containing 
the expression that is the current level 
list. If not found, no chance is made in 
the state of the edit. Note: it is unnecessary 
to have SUPEREDITFLG set to T to execute («- COND) 
Also («-F COND) is the same as («-F). 
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Miscellaneous Features 



(X CONTAINING . @) 



Locates X, then locates @ locally , I.e., 
find commands will not go outside of the 
expression headed by X, and then backs up 
to X using the «- command, so that 
(X CONTAINING Y) will find the inner X in 
(X ... (X ...Y) ..). Note: X will be 
located regardless of the setting of 
SUPEREDITPLG : (X CONTAINING . @) is 
identical to (LC P X (LCL . @) (+ X)). 



Example: 

(SECOND (COND CONTAINING (SETQ CONTAINING CDR) ) 



(EVERY . @) 



is built into the locate routine. Whenever 
(CAR @) = EVERY, the locate routine looks 
back up the push down list and finds the 
command containing this specification, and 
instead performs the corresponding 
LP command, e.g., (MBD (EVERY X) LIST) is 
equivalent to (LP (MBD X LIST)). 



(ALL . @) 



same as EVERY. 



Sentence Format 

In addition to the command followed by arguments format, the user can 
employ a more flexible, sentence-type format when communicating 
with the editor. The chief advantages of this format are that 
the names of the commands and the order of the arguments are 
somewhat more intuitive, and that there are considerably fewer 
parentheses required. 
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The following is a list of sentence-types permissible: (*)■ 

(INSERT . ... BEFORE . . .) 
( INSERT . . . AFTER . . . ) 
( INSERT . . . FOR . . . ) 
(PUT ... BEFORE ...) 
(PUT . . . AFTER . . .) 
( REPLACE ... BY ... ) 
( REPLACE . . . WITH . . * ) 

(CHANGE ... TO ...) 
(DELETE ...) 
(EMBED ... IN ... ) 
(EMBED . . . WITH . . . ) 
(MOVE ... TO AFTER . . .) 
(MOVE ... TO BEFORE ...) 
(SURROUND . . . WITH . . .) 
(SURROUND ... IN ... ) 
(EXTRACT . . . FROM . . .) 
(SWITCH . . . AND . . . ) 



Examples: 

(INSERT (PRINT Y) AFTER -1 NULL) 

(REPLACE CDR WITH CAR) 

(REPLACE CDR WITH (CAR X)) 

(EMBED EVERY PRINT IN (COND (FLG *))) . 

(DELETE (COND CONTAINING RETURN)) 

(EXTRACT (SECOND SETQ) FROM (COND CONTAINING GO)) 



(*) "..." indicates a segment of a list, i.e., no parentheses are 
used around "..." even if it consists of several elements, see 
examples. 
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Summary of New Commands 

Following is a complete list of the commands in the expanded 
editor. The ordering is that of their position on EDITMACROS. 

UP 
NX 
BK 

A 

B 

MBD 

SW 

XTR 

MV 

LP 
* 

LC 

ORR 

LPQ 

9 

DELETE 

TTY 

STOP 

•* (when used in a list) 

SECOND 

THIRD 

LCL 
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EDITA 

The increasing number of applications of LISP that involve arrays 
have motivated the implementation of EDITA, an editor for arrays. 
EDITA can be used on any LISP array, including those containing 
list structure or unboxed numbers, or both, or on compiled function 
definitions. 

To the user, EDITA looks very much like DDT with some LISP 
extensions. It is a function of one argument :* the array or func- 
tion to be edited. This can be specified directly or indirectly, 
i.e., you can type EDITA(A), or perform (EDITA A) inside of some 
other form. EDITA performs an EVAL on its first argument if it 
is not already an array or a function. 

Once inside of EDITA, individual "registers" or cells in the 
array may be examined by typing their address followed by a 
slash, e.g. , 

V 6 

i.e., (ELT A 4)=6.** An address consists of a number or a LISP 
form whose value is a number, or a series of numbers or forms 
which yield numbers. In the latter case, the address is computed 
as the sum of the forms, e.g., 
4 X (MINUS (CAR Y)) / ... 
(CAR (CHCON (QUOTE A))) / . . . 



* An optional second argument can be a list of commands to edita 
These are executed exactly as though they had come from the 
teletype. 

** If the register is in the unboxed area of the array, the 
boxed contents are printed. 
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The variable "." has the value of the address of the current (last) 
register examined, and the variable $ has the value of the last 
register in the array, i.e., (ARRAYSIZE A), e.g., 



$ (MINUS .) / 
. ./ 



• • • 



• • • 



are acceptable. Since EDITA uses its own read program, it is not 
necessary to surround the period in double quotes. Also, since 
carriage return has a special meaning, the balancing of paren- 
theses in any LISP expression is indicated by a space, 
instead, of a carriage return as with the LISP reader. This is the 
explanation of the extra space before the slash in some of the 
examples above. 

A slaish- is really a command to EDITA to "open" the indicated 
register. Only one register at a time can be open, and only 
open registers can be modified. To change the contents of a 
register, the user first opens it, types a form* and then closes 
the register with a carriage return, e.g., 

V 6 (FACTORIAL .) x 
./ 2k 

Note: Computations can be executed while a register is opened 
without changing its contents. The contents of a register are 
changed only when it is explicitly closed by a carriage return, 
line feed, or t. If the register is in the unboxed region of the 
array, an unbox will be automatically performed before storing 
the new value into the array. 

* In the boxed region of the array, only non-atomic expressions 
are evaluated; in the unboxed, all expressions are evaluated. 
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If a form is typed followed by a carriage return when no register 
is open, the form is simply evaluated and its value typed, e.g., 

V 4096 q 
(RADIX 8)- 
(10 T) *r 
./ 10000Q 

Used in this way, EDITA behaves the same as BREAK. 

EDITA also recognizes the following commands: 

OK which causes a return from EDITA 

with the value the array being 
edited. 

linefeed which closes any open register and 

opens the next register, i.e., it 
is the same as carriage return 
followed by (ADD1 . ) 

+ same as carriage return followed 

by (SUB1 .) 

= (when not preceded by a space) 

causes EDITA to type value of last 

expression, e.g., 

. = V 6 (PRIME 6) = 11 (PRIME 7 )/} 

../ 13 

If a register is open, the = 
command also operates to negate 
the effect of any previous user 
input so that if the register is 
closed following an = command, it 
will not be changed. 

;Q has value of last expression typed 

by EDITA, e.g. , 

V 6 (FACTORIAL . )=24 (ADD1 ;Q)~ 
./ 25 
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t (when register is already open), 

if preceded by user input , EDITA 
prints the contents of the indi- 
cated register, otherwise EDITA 
prints the contents of the register 
whose address is the contents of 
the currently open register, 
e.g., 

V 6 / 10 } 
6/ 10 V 6 " 

This command does not affect the 
currently open register. 

Tab (control I) similar to / except it closes the 

currently open register (if any) 
and opens the indicated register, 

tab 
9tab 



v 


6 


6/ 


10 


9/ 


11 



If the contents of the currently 
open register is not a number, 
but is another array , or the 
name of a function - tab will 
call EDITA on it. 



In all cases only low order 14 bits used ; 
Underlined characters were typed by user. 



9.44 



? negates all user input not yet 

processed, leaves state of registers 
unchanged. 

AD1,AD2/ where AD1 and AD2 are addresses, 

causes the contents of registers 
AD1 through AD2 inclusive to be 
typed, "." is set to AD2 after 
completion. 

;W expr searches array and prints all 

registers whose contents "equal" 
expr , in the sense of the match 
used by the editor, e.g., ;W (&) 
will find and print all registers 
containing a list consisting of a 
single element. After search, 
"." is left set to the last such 
register. 

expr ;W same as above except that since 

expr will have been evaluated 
before the ;W command was read, 
its value will be used in the 
search, e.g., (CADR X) ;W 
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If the search command is prefaced by an address and a comma as in 
POO 2 y ;W NIL or 25, X ;W the search will begin at the indicated 
register , otherwise it begins at register ".", the last opened 
register. If the search is to begin in the unboxed region of 
the array, the value to be searched for must be a number and is 
compared with the result of boxing each element in the unboxed 
region. The variable MASK can be set prior to the search for 
comparison with just selected bits in the word. The search 
terminates at the end of the unboxed region of the array. 

If the value to be searched for is not numeric, no attempt will 
be made to search the unboxed region of the array, regardless of 
the value of "." or the address specified, i.e., the search 
automatically begins at BOXED if "." is less than BOXED. 

:name defines name as either (1) the 

contents of register ".", or if 
no register open (2) the address 
typed just before the :, or if 
none was typed, (3) the value of 
".". * For example, 

V 6 :P00 
:PIE 
. 1:FUM 
defines F00 as 6, PIE as H and FUM as 5. 

EDITA keeps its "symbol tables" on two free variables, USERSYMS 
and SYMLST. USERSYMS is a list of elements of the form 
(name . value) and is used for encoding input, i.e., all variables 
on USERSYMS are bound to their corresponding values during evalua- 
tion of any expression inside EDITA. SYMLST is a list of elements 
of the form (value . name) that is used for decoding addresses, 

* Only low order 14 bits are used. 
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and in the case of editing compiled functions, decoding instruc- 
tions. USERSYMS is initially set to NIL, while SYMLST contains 
certain system parameters such as PPPTR and SPCELL.* Since the : 
command adds the appropriate information to these two lists, new 
definitions will remain in effect even if the user exits from 
EDITA and then reenters it later. 

Note that the user can effectively define symbols without using the 
command by appropriately binding USERSYMS and/or SYMLST before 
calling EDITA. Also, he can thus use different symbol tables for 
different applications. 

Some general comments 

Although EDITA uses its own read program, ** which is not line 
buffered, it does respond to control-A and control-Q in the same 
way as the LISP read program does in almost all situations. In 
those cases where it cannot delete previous characters because 
they have already been processed, EDITA will ring the teletype 
bell to signal its frustration. Similarly double quotes can be 
used to input expressions containing break characters for EDITA 
such as /, (, ?, etc. 

EDITA is buffered against errors and rubouts. Whenever an error 
occurs or a control-R is typed, EDITA responds with a ? and closes 
any open registers (without modifying them) and clears any flags 
that may have been set during the user's last request. It is 
quite safe to hit control-R at any time during EDITA 1 s operation. 

EDITA will not allow the user to reference any registers outside 
the- bounds of his array. 



* It is not necessary to place a symbol on USERSYMS that already 
has a binding, such as PPPTR or SPCELL, since the correct value 
will be obtained when the form in which it appears is evaluated 

** Actually, EDITA uses the FLIP read program so do not flush 
FLIPREAD if you olan to use EDITA. 
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Using EDITA on compiled functions 

Since a compiled function is actually an array with the instructions 
of the function corresponding to the unboxed region of the array 
and the literals to the boxed region, EDITA could be used on a 
function definition exactly the same as though it were an array 
generated via ARRAY. However, certain extensions and modifications 
to EDITA have been made to facilitate its use with compiled func- 
tions with the result that EDITA operates somewhat differently 
when working with a function than with an array, although the 
basic idea and philosophy of its use remains the same. 

The first difference to be noted is that by convention the first 
element of an array has address 1, while the first instruction of 
a function definition has address 0. In other words, the instruc- 
tion LDA 25 loads the accumulator with what would be register 26 
in an array. EDITA takes care of this problem automatically both 
on input and output by following one address convention for func- 
tions and the other for arrays. 

The greatest difference - and the most useful feature of EDITA in 
conjunction with functions - is the decoding of instructions. 
EDITA decodes the contents of all cells in the unboxed portion of 
the function definition (in the boxed region, EDITA operates 
exactly as it does with an array except that the address convention 
is that of function definitions) and types their mnemonic, address 
portion, and indirect bit or index register if any. The address 
portion is further decoded using SYMLST. Here are some examples: 
LDX PPPTR; STA 25,2; L DA* F00; CONSCLL. The decoding of the 
address portion also notes references to literals in the function 
definition and prints the literal preceded by an "=", instead of 

its address, e.g., LDA =(-ARGUMENTS ?); XCLL =PRINT. References 
to small integers are also detected, e.g., SUB =1; SKG =5. 
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Symbolic input is available, although it is not quite as sophis- 
ticated as the output decoding. Op codes are recognized, as are 
small integers (this is why the = command must be preceded by a 
space: to distinguish it from a small integer). However, the 
indirect bit must be indicated by means of the variable J, and 
the index register by I. For example, the following is permissible 
input: LDX PPPTR; STA 25 I (which would be typed back as 
STA 25,2) LDA F00 J, SUB =1. LDA =( -ARGUMENTS ? ) is not ner- 
missible. To input this the user would have to know the address 
of the register containing the literal ( -ARGUMENTS ?). 

When an op code is seen, all subsequent arithmetic is done in the 
low 14 bits of the word only, so that LDA -1 is equivalent to 
LDA 37777Q, not to SKD* 37777Q. 

There are two other small differences when editing a function. 
First, read-only out of bounds references are permitted, 
e.g., 3/ LDX PPPTR / 27. Secondly, the search option will 
automatically mask out the address or instruction portion of the 
word if the value to be searched for is just an instruction or 
an address. For example, LDA =5 ;W will find all occurrences of 
that instruction, LDA ;W will find all LDA instructions, =5 ;W 
will find all references to the small integer five. The user 
can of course still set the variable MASK. 
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SECTION X 



ATOM, ARRAY, AND STORAGE MANIPULATION 



pack[x] 



The argument x of pack must be a 
list of atoms. The value of pack 
is a single atom whose print name 
is a packed version of the print 
names of all the atoms given in the 
list. Thus: 

pack[(A BC DEF G)] = ABCDEFG 
pack[(l "." 3)] = 1.3 a floating 

point number 



unpack [x] 



The argument of unpack should be an 
atom. The value of unpack is a list 
which contains, in order, the char- 
acters which make up the print name 
of that atom. 



nthchar[atom;n] 



Returns the nth character of atom 
as a single-character atom. Equiva- 
lent to (CAR (NTH (UNPACK atom) n)), 
but is faster and does no CONS T es. 
See note after loc, p. 10.4. 



nchars)[atom] 



Returns number of characters in 
atom . Thus the last character in 
an atom is given by 

nthchar [ at om; nchars [ at om] ] 
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chcon[x; j ] 



Returns a list of numbers represent- 
ing characters in print name of x 
which must be an atom. 

j = NIL prinl representation 
= T prin2 representation 



character[n] 



gensym[] 



n is a character code. Value is 
atom having single character as its 
P-name, e.g., character[8]= M (" . 

This function of no argument gener- 
ates a unique symbol of the form 
Annnrij in which each of n's is 
replaced by a digit. Thus, the 
first one generated is A0001, etc. 
This is a way of generating new 
atoms for various uses within the 
system. 



oblist[] 



reclaim[flg] 



Creates a list of all atoms 
currently in the system. 

Initiates a garbage collection. If 
fig is T, all spaces are collected: 
list words, atoms, large numbers, 
floating point numbers, arrays and 
binary programs. If fig is NIL, 
array space (identical to binary 
program space) is not collected, 
fcut all others are. Value of 
reclaim is number of list words 
available and will be ^> the setting 
of minfs unless the total list 
space has been exhausted. See p. 3.8- 
3.12 for more detailed discussion of 
garbage collection. 
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atomgc[flg] initiates a reclaim which also 

collects any unused atoms that 
were previously in the shared system 
but have been released by flushing 
some portion of it. See p. 3.8-3.12 
for discussion of garbage collection 
and p. 22.8 for flushcode . Argument 
fig is the same as in reclaim. 

gctrp [n] garbage collection trap. Causes a 

(simulated) control-H interrupt when 
number of free words left equals n, 
i.e. when a garbage collection would 
occur in n more conses. 

At this point, the user can turn off 
the display, list a file, logout of 
LISP, etc. arm described on p. 22.2 
shows how the user can automate this 
procedure. 

Value of gctrp is last setting. If 
n=NIL, value of gctrp is number of 
words left, i.e. (GCTRP (PLUS (GCTRP) 
-10)) will cause a trap after 10 more 
conses. 
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minfs[n] Sets the minimum amount of free 

storage which will be maintained by 

the garbage collector. If, after 

any garbage collection, fewer 

than n free words are present, 
sufficient storage will be added in 

128 word chunks to raise the level to n 

The user may also change the setting 
of minfs at any time, even during a 
garbage collection, by typing control-P 
followed by a number (which becomes 
the new setting) followed by a 
period. 

gcgag[x] If X =T garbage collector will print 

a message when entered. If x=NIL no 
message is printed. Previous setting 
is returned. Initially set to T. 

logout [] Deactivates users program and. returns 

the user to the time-sharing system 
executive. Closes all open files. 

closer[a;x] Stores x into location a. Both x 

and a must be numbers. 

a<2 actual core location 

-i u 
a>2 address in virtual 

address space. 

openr[a] Value is number in a as defined 

in close r. 

loc[x] Makes a number out of x, i.e. 

returns the virtual address of x. 

Note: for alphabetizing purposes, it is useful to note that the 
atoms consisting of a single character are stored in ASCII code 
order, i.e. loc[A] < loc[B] < locTC] etc. 
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vag[x] The inverse of loc . x must be a number. 

value is the unbox of x. An unboxed 
number n which doesn't correspond to 
the address of a list structure or an 
atom is printed #n, n is given in octal, 
e.g. array pointers are printed this way. 

Note: unboxed numbers should not be passed around as ordinary 
values because they can cause trouble for the garbage collector. 
Everything in LISP is essentially an unboxed number, i.e. an ad- 
dress. However, certain unboxed numbers are recognized as being 
of certain data types, e.g. integers, atoms, list structure, etc. 
If you creat an unboxed number that happens to correspond to an 
address in list structure, the garbage collector will not be able 
to distinguish this from a bona fide list structure. For example, 
suppose the value of x were 150000, and you created (VAG X), and 
this just happened to point into the free storage list! The next 
garbage collection would be disastrous. 

allocate [n] Allocates an n word block in array 

(binary program) space. Returns a 
pointer to the address of the first 
word allocated. If sufficient 
space is not available, a garbage 
collection of array space (RECLAIM T) 
is initiated. If this is unsuccessful 
in obtaining sufficient space, an 
error is generated. 

statistics[] Prints out statistics on number 

of wraparounds of compiled code; 
number of mapped stores; total 
number of mapped references ( car ' s , 
c_dr ' s , cons's, rplaca ' s , rplacd * s, 
getd's, etc.); number of drum reads; 
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number of drum writes; number of 
drum reads for binary function 
loading; number of function calls 
from binary code. Names and loca- 
tions of cells printed are bound 
at top level to STATCELLS. 

clearstat[] Sets to all statistics cells in 

the list bound to STATCELLS. 

storage[] Prints out current status of 

storage including number of binary 
program (array) words in use; number 
of list words (two 940 words) in 
use; number of 940 words available; 
and number of words used up for 
print names. 

Array Functions 

Space for arrays and compiled code are both allocated out of a 
common array space. Arrays of pointers and unboxed integers 
may be manipulated by the following three functions: 

array [n,p,v] This function allocates a block of 

n+4 940 words, of which the first 
4 are header information. The next 
p<n are cells which will contain 
unboxed integers, and are initialized 
to 0. The last n-p:>0 will contain 
pointers initialized to v. If p is 
NIL it is assumed equal to (i.e., 
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elt[a;m] 



a symbolic array). The value of 
this function is the location of 
the array in virtual memory, and 
is called an array pointer. Array- 
pointers print as In, where n is the 
octal representation of the pointer. 
Note than, #n will be read as an 
atom, and not an array pointer. 

Has as value the m element of 
the array pointed to by a. For 
out of bound calls, if m<l or m>n, 
where n is the length of the array 
a, elt gives element 1 if m<l, or 
element n if m>n. 



seta[a;m;v] 



Sets the value of the m element 
of a to v. On out-of-bounds 
reference no store is made. The 
value of this function is always 
v. It is the users responsibility 
to ensure that no pointers are 
placed in the non-pointer area. 
Any in that area will not be 
traced during garbage collection. 



arraysize[a] 



Returns the size of array a if a 
is an array pointer. 



arraypCx] 



Returns T if x is a pointer into the 
active array area, otherwise NIL. 
No check is made to ensure that x 
actually addresses the header of a 
legitimate array. 
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SECTION XI 

FUNCTIONS WITH FUNCTIONAL ARGUMENTS 

As in all LISP 1.5 Systems, arguments can be passed which can then 
be used as functions. Functions which use functional arguments 
should use variables with obscure names to avoid conflict of vari- 
able names with variables used free in a functional argument. 
There is no "FUNARG device" used in this system. All system func- 
tions standardly use variable names consisting of the function 
name concatenated with x or fn etc. A FUNARG device may be 
implemented in the future. 



function[x] 



Identical to quote for interpreted 
code. When compiled, function[x] 
will cause x to also compile, 
quote[x] will not. 



map [mapx ; map f nl ; mapf n2 ] 



If mapfn2 is NIL (i.e. not provided) 
this function applies the function 
mapfnl to successive tails of the list 
mapx . That is, first it computes 
mapfnl [mapx], and then mapfnl[cdr[mapx]] , 
etc. until mapx is NIL (mapx is reset 
at each iteration so that its value is 
always the current tail); however, if 
mapfn2 is provided, mapfn2[mapx] is 
used instead of cdr[mapx] for the next 
call for mapfnl . Thus if mapfn2 were 
cddr , alternate elements of the list 
would be skiooed. If mapfn2 is a 
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map c [mapx ; map f nl ; map f n 2 ] 



conditional expression, then the next 
element to be looked at can be con- 
tingent on ^a computation. 

Identical to map , except that 
mapfnl [car [mapx ] ] is computed each time 
If mapfn2 is NIL, mapfnl is applied to 
each element of the list x in turn. 



map car [mapx; mapfnl ;mapfn2] 



If *na.pfn2 is NIL, this function applies 

the function mapfnl to each of the 

elements of the list mapx . It creates 

a new list which is a map of the 

old list in the sense that each 

element of the new list is the 

value of applying mapfnl to the 

corresponding element of the old 

list. If mapfn2 is provided, mapfn2[mapx] 

is used instead of cdr[x] for each 

succeeding computation with mapfnl . 



map list [mapx; mapfnl; map fn2 j 



This function computes successively 
the same values that map computes; 
it forms a new list consisting of 
successive values of applications 
of this function. 



map cone [map x ; map f n 1 ; map f n 2 ] 



Identical to map car except that it 
does an nconc instead of a cons . 
This makes it useful for constructing 
a new list from an old one where a 
variable number of elements is to be 
inserted at each iteration. 
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mapcon [mapx ;mapf nl ; mapf n2 ] 



Identical to maplist except that it 
does an nconc instead of a cons . 



map2c[mapx;mapy;mapfnl;mapfn2] Identical to mapc except mapfnl is 

a function of two arguments, and 
mapfnl [car [mapx]; car [mapy]] is computed 
each time. Terminates if either 
mapx or mapy become MIL. 

map 2 car[miapx; mapy; mapfnl; map fn2] Identical to map car except mapfnl 

is a function of two arguments and 

mapfnl[car[mapx];car[mapy]] is used 

to assemble the new list. Terminates 
if either mapx or mapy become NIL. 

mapa[mapary;mapfnl;mapfn2;mapn] Cycles through mapary , an array, 

applying at each iteration the 
function mapfnl , a function of 
two arguments, to map ary and n 
the index of iteration, n is 
initially set to 1, and reset to 
mapfn2[n], if mapfn2 is given, 
otherwise addl[n]. Process 
continues until n exceeds mapn , 
if given, or else 
array size [mapary]. The value of 
map a is mapary . 

Example: the following function 
will copy an array: 

(LAMBDA (A) (MAPA (ARRAY (ARRAYSIZE A)) 
(FUNCTION (LAMBDA (Al N) 
(SETA Al N (ELT A N)))))) 
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maprint[lst;fl;l;r;s;pfn;c] 



every [ e veryx , every f] 



some [somex; somef ] 



is a general printing function. It 
cycles through 1st applying pfn 
(or prinl if pfn not given) to each 
element of the 1st . Between each 
application it performs prinl of s_, 
or " " if not given. If 1 is given, 
it is printed (prinl) initially; 
if r is given, it is printed (prinl) 
at the end. fl is the file used for 
all printing, c a special argument 
used by prettyflip . 

For example, maprint[x;NIL ;"(",")" ] 
is equivalent to print. To print a 
list on the tty with commas between 
each element and a final " . " one 
could use maprintCx;T;NIL;". ";","]. , 

is true if everyf applied to each 
element in everyx is not NIL, e.g., 
every [(X.Y Z); ATOM]=T. . 

is NIL if somef applied to every 

element in somex is NIL, otherwise 

it is the list beginning with the 

first element that satisfies somef , 

e.g., 

somef [x 3 (LAMBDA (X) (EQUAL XI))] 

is equivalent to member Cx,y]. 



mapdl 
searchpdl 



see p. 12.9 



see p. 12.10 
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SECTION XII 

VARIABLE BINDINGS AND PUSHDOWN LIST FUNCTIONS 

A number of schemes have been used in different versions of LISP 
for storing the values of variables. These include: 

1. Storing values on an association list paired with the 
variable names. 

2. Storing values on the property list of the atom which is 
the name of the variable. 

3. Storing values in a special value cell associated with 
the atom name, putting old values on the pushdown list, 
and restoring these values when exiting from a function. 

4. Storing values on the pushdown list. 

The first three schemes all have the property that values are 
scattered throughout list structure space, and, in general, in a 
paging environment would require references to many pages to deter- 
mine the value of a variable. This would be very undesirable in 
our system. In order to avoid this scattering, and possible ex- 
cessive drum references, we utilize a variation on the fourth 
standard scheme, usually only used for transmitting values of 
arguments to compiled functions; that is, we place these values 
on the pushdown list. But since we use an interpreter as well as 
a compiler, the variable names must be kept. The pushdown list 
thus contains pairs, each consisting of a variable name and its 
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value. The interpreter need only search down the pushdown list 
for the binding (value) of a variable. 

One advantage of this scheme is that the current top of the 
pushdown stack is usually in core, and thus, drum references are 
rarely required. Free variables work automatically in a way 
similar to the association list scheme. 

An additional advantage of this scheme is that it is completely 
compatible with compiled functions which pick up their arguments 
on the pushdown list from known positions, instead of doing a 
search. To keep complete compatibility, our compiled functions 
put the names of their arguments on the pushdown list, although 
they do not use them to reference variables. Thus, free variables 
can be used between compiled and interpreted functions with no 
special declarations necessary. The names on the pushdown list 
are also very useful in debugging, for they provide a complete 
symbolic backtrace in case of error. Thus, this technique, for 
a small extra overhead, minimizes drum references, provides 
symbolic debugging information, and allows completely free mixing 
of compiled and interpreted routines. 

There are two pushdown lists used in BBN 9^0 LISP: the first 
is called the parameter pushdown list, and contains pairs of 
variable names and values, and temporary storage of pointers; 
the second is called the control pushdown list, and contains 
function returns and other control information. 

However, it is more convenient for the user to consider the 
push-down list as a single "list" containing the names of functions 
that have been entered but not yet exited, and the names and values 
of the corresponding variables. The multiplicity of push-down lists 
in the actual implementation is for efficienty of operation only. 



12.2 



The Push-Down List and the Interpreter 

In addition to the names and values of arguments for functions, 
information regarding partially-evaluated expressions is kept on 
the push-down list. For example, consider the function FACT: 

- PRETTYPRINTC (FACT3 

< FACT 

(LAMBDA (N> 
(COND 

((ZEROP N> 

L) 
(T (TIMES N (FACT (SUB1 N)))>)>> 
N IL 



As soon as FACT is entered, the interpreter begins evaluating the 
implicit PROGN following the LAMBDA (see p. 4.3-4.4). The first 
function entered in this process is COND. COND begins to process 
its list of clauses. After calling ZEROP and getting a NIL value, 
COND proceeds to the next clause and evaluates T. Since T is not 
NIL, the evaluation of the implicit PROGN that is the consequent 
of the T clause is begun (see p. 4.3). This requires calling the 
function TIMES. However before TIMES can be called, its arguments 
must be evaluated. The first argument is immediately evaluated, 
but the second involves a recursive call to FACT, and another 
implicit PROGN," etc. 

Note that at each stage of this process, some portion of an ex- 
pression or argument list has been evaluated, and another is await- 
ing evaluation. This information is recorded on the pushdown 
list as follows: 
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1. Whenever a FSUBR* function is entered, i.e. COND, PROG, OR, 
AND, SETQ, PROGN, or implicit PROGN (*), the variable NLAMBDA is 
bound on the push-down list to the rest of the expression following 
the FSUBR*. (Since implicit PROGNs do not appear on the push-down 
list as specific function calls, this binding will appear following 
the variables of the function previously called.) As the FSUBR* 
processes its "argument list," the binding of NLAMBDA is updated 

so that car of its value is always the expression currently being 
worked on. This is more than just a diagnostic device: the slot 
on the push-down list corresponding to the binding of NLAMBDA is 
actually where the FSUBR* keeps the expression it is processing. 
If a function subsequently entered modifies this binding, the 
FSUBR* would continue with the evaluation of the modified expres- 
sion when control returned to it. 

2. Whenever a form is encountered that is headed by a function of 
type EXPR, EXPR*, C EXPR, CEXPR*, SUBR, or SUBR*, i.e. those requir- 
ing evaluation of arguments, the function name is entered on the 
push-down list and the variable LAMBDA is bound to its argument 
list. The arguments are then evaluated in turn from left to right. 
As each argument is evaluated, it is bound to a variable name select- 
ed from the atoms a,b,c, ... z (**),i.e. the first is bound to a, 
the second to b, and so forth, and LAMBDA is bound to cdr of its 
previous value. Thus car of the value of LAMBDA is always the 



(*) QUOTE, GO, and FUNCTION are also FSUBR* type functions, but 

since no evaluation of forms takes place inside of them, they 
do not modify the push-down list. 

(**) Note that these are lower-case characters not present on 
model teletype model 33 keyboards. They print out as %A S 
%B etc. as described on page 14.4. To evaluate %A S perform 
(EVAL (CHARACTER 65)), %B, (EVAL (CHARACTER 66)), etc. 
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argument currently being evaluated. 

When all of the arguments to the function are evaluated, the function 
is called, and the values of the arguments bound to the names of the 
arguments of the function. The bindings for LAMBDA, and a,b, etc., 
disappear. Thus a function has actually been entered if and only if 
it does not have a binding for the variable LAMBDA. 

The following untrace illustrates the above discussion: 
- PRETTYPRINT( (FACT) > 

( FACT 

(LAMBDA <N> 
(COND 

((ZEROP N) 

L) 
(T (TIMES N (FACT (SUB1 N>>>>>>> 
N IL 
-FACT(2) 

ERROR 

( L IS UNBOUND ATOM) 

UNTRACE: 

NLAMBDA (L) 
COND 

NLAMBDA ((COND ((ZEROP N) L) (T (TIMES N (FACT (SUB1 N)))))) 

N 
FACT 

LAMBDA ((FACT (SUB1 N))> 

%A 1 
TIMES 

NLAMBDA ((TIMES N (FACT (SUB1 N)))) 
COND 

NLAMBDA ((COND ((ZEROP N) L) (T (TIMES N (FACT (SUB1 N)>>>>) 

N 1 
FACT 

LAMBDA ((FACT (SUB1 N>>) 
%A 2 
T IMES 

NLAMBDA ((TIMES N (FACT (SUB1 N)>)> 
C OND 

NLAMBDA ((COND ((ZEROP N) L) (T (TIMES N (FACT (SUB1 N)))>)> 

N 2 
FACT 
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The Push-Down List and Compiled Functions 

In addition to the function names and values of arguments to com- 
piled functions, the push-down list contains the names and values 
for all free variables used in compiled functions, as well as any 
variables that are locally bound by PROGs or open-LAMBDA expressions.* 
The free variables follow the arguments to the function on the push-down 
list. Locally bound variables are stored on the push-down list 
following the next function call. See p. 16.26-27 for more 
detail. 



(*) In interpreted functions, the PROG or open-LAMBDA would be 
called as a regular function and the bindings of their 
variables would automatically appear as arguments on the 
push-down list. 
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Pushdown List Functions 



The following functions allow one to interrogate the pushdown list(s) 
from inside another function. The convention used by these functions 
regarding push-down list positions is that the position number, n, if 
positive, is the number of function calls which have been made - 
essentially the depth of nesting of functions from the top level. If 
n is negative, it references back from the current call level. For 
example, on the previous page, the position of the last call to fact 
is either -2 or 6. 



nthfnback[n] 



Returns the name of function called 
at call level (position) n 



nthfn[fn;n] 



evalv[var ;n] 



setv[var; n; val] 



Returns the position (number of 
call levels from top) of the nth 
occurrence back of function named 
In, e.g. nthfnback[nthfn[fn,l]] = fn 

Returns the value of variable var 
evaluated starting at pushdown list 
position n 

Sets the value of variable var 
starting at pushdown position n 
to value val 



variables[n] 



Returns list of variable names on 
pushdown list at pushdown position 
n, including LAMBDA, NLAMBDA, and 
#A-type bindings if any, as well as 
free and locally bound variables 
for compiled functions as described 
earlier. 



rename[old; n; new] 



The variable named old at level n 
will be renamed new . The push-list 
cell containing the variable name 
is changed. 
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retfrom[n;v] 



Retu rns from the function at 
position n, with value v, i.e. 
jumps back up the pushdown list 
through all intervening function 
calls. 



backtrace[n;m] 



Prints out the untrace normally 
associated with errors, starting 
at position n, and going back 
to position m (i.e. n>m) . If 
n=NIL; it is assumed equal to 
current position; if m=NIL; it 
is assumed equal to 0. 



baktrace[n] 



Like backtrace except it skips 
over calls to breakl , faultl , 
faulteval , interrup t, error , etc 
Used by the BT macro in break. 



rtfrm[rtfn;rtform;rtn] 



is an NLAMBDA that provides a con- 
venient way of calling ret from , e.g. 
(RTFRM F00 X 2) is equivalent to 
(RETFROM (NTHFN (QUOTE F00) 2) X). 
It does a ret from from nthfn[rtfn;rtn], 
(if rtn is not given, 1 is used) with 
the value of rtform. 
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mapdl[mpdlfn;mpdln] 



cycles back up the push-down 
list, starting at position mp_dln, 
(if mpdlr:=NIL, it is set to 
nthfn[mapdl;l]) applying mpdlfn 
to the function entered at that 
push-down position, i.e., to 
nthfnback[mpdln] and then decre- 
menting mpdln by 1 until it 
reaches 0. For example: 



mapdlC (LAMBDA (X) (COND 

((EQ (FNTYP X) (QUOTE EXPR) ) 
(PRINT X))))) 

will print all EXPRs on the push 
down list. 

Note: Negative value for mpdln 
may be used. 

Value of mapdl is NIL. 
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searchpdl[srchfn;srchm] searches the push-down list 

until it finds a position for 
which srchfn, applied to the function 
called at that position, is not NIL. 
For example, 

(SEARCHPDL (FUNCTION (LAMBDA (X) 
(NOT (ATOM (GETD X)))))) 

will find the last EXPR called. 

If srchm is not given, the search 
begins with the function called 
just before searchpdl . If srchm 
is supplied and is not a number, 
the search begins as of 
(NTHFN SRCHM 1), otherwise search 
begins with srchm . Note that 
srchm is bound to the push down 
list position at all times, so 
that srchfn can use it for calling 
evalv , setv, or ret from . The value 
of searchpdl is (function . position). 
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Push-Down Handles 

This section describes how to write functions which directly 
manipulate the push-down lists, e.g. an nthfn that starts at a 
specified point, or one that searches forward instead of backward, 
a form of variables that checks to see if a particular variable 
is bound without creating a list of all variables, etc. 

There are four free variables which provide a direct handle on 
the two push lists: 

CP Control PDL Pointer 

ICP Initial CP 

PP Parameter PDL Pointer 

IPP Initial PP 

The value of each of these variables (also stored under the 
property COREVAL on their property list) is a number which is the 
location of a cell in core which contains a virtual memory address 
These addresses define the bounds of their respective push-lists: 
IPP and ICP are the initial values, PP and CP the current values 
(actually they point to the first cell not used). Thus if both 
stacks are empty, i.e. at the top level 
(OPENR CP) = (OPENR ICP) 
and (OPENR PP) = (OPENR IPP) 

For each function called, the contents of CP are increased by 4, 
corresponding to the four cells required on the control push-down 
list for information about this function call. The first two of 
these cells contain the functions return and its virtual address, 
so should not be of interest to the user. However, the third 
cell, i.e. (OPENR ICP)+2,+6,+10. . . contains the functions name. 
Thus, the following definition of nthfn is equivalent to the 
machine coded one currently in our system. 
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(NTHFN 

(LAMBDA (FN N) 
(PROG (X Y) 

(SETQ X (PLUS (OPENR CP) 

(SETQ Y (OPUNR ICP) ) 
LP (COND 

( (EQ (CAR (VAG (PLUS X 2) ) ) 
FN) 
(COND 

( (ZEROP (SETQ N (SUB1 N) ) ) 

(RETURN (QUOTIENT (DIFFERENCE X Y) 

(COND 

( (NEQ (SETQ X (PLUS X ~4)) 
Y) 
(GO LP))) 
(RETURN NIL) 
))) 



The fourth cell on the control push-down list is a pointer to the 
first cell on the parameter push-down list used by this function. 
For each variable bound locally by a function, the contents of PP 
are increased by two, i.e. each variable uses two cells on the 
parameter push-down list. The first cell, i.e. (OPENR IPP)+0,+2,+4 . 
contains the value of the variable; the second contains its name. 
Thus, variables can be recognized on the parameter push-down list 
by the appearance of an atom, the variable f s name, in an odd cell*. 
Thus, the following definition can be used for variables: 



The parameter push-down list is used for temporary storage by 
the interpreter, and also contains information about bindings 
of free variables in compiled functions. Thus, from the user ! s 
standpoint, it may contain some "garbage". 
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(VARIABLES 
(LAMBDA (N) 

(PROG (LST FROM TO Z) 

(SETQ FROM (OPENR (SETQ N (PLUS (OPENR ICP) 
(TINES N 4) 
3)))) 
(SETQ TO (OPENR (PLUS N 4))) 
LP (COND 

( (EQ FROM TO) 

(RETURN LST) ) 
((ATOM (SiiTQ Z (CAR (VAG (ADD1 FROM))))) 
(SETQ LST (NCONC LST (LIST Z))))) 
(SETQ FROM (PLUS FROM 2)) 
(GO LP) 
))) 



The following function is presented as an example of a "new" 
push-down list function. Its value is T if the variable VAR is 
bound by the function at position N on the push-down list, other- 
wise NIL. In other words, it is equivalent to (MEMBER VAR (VARIABLES N))., 



(VARIABLE? 

(LAMBDA (N VAR) 
(PROG (FROM TO) 

(SETQ FROM (OPENR (SETQ N (PLUS (OPENR ICP) 
(TIMES N 4) 
3)))) 
(SETQ TO (OPENR (PLUS N 4))) 
LP (COND 

( (EQ FROM TO) 

(RETURN NIL) ) 
((EQ (CAR (VAG (ADD1 FROM))) 
VAR) 
(RETURN T) ) ) 
(SETQ FROM (PLUS FROM 2)) 
(GO LP) 
))) 
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SECTION XIII 



ARITHMETIC FUNCTIONS 



Integer Arithmetic 

The following functions all work on integers. When given floating 
point numbers as arguments, these arguments are fixed (converted 
to integers) before any operation is performed. Most of these 
functions are compiled as open code. 

plus[x-. ;x 2 ; . . . ;x ] Returns an integer x,+Xp+...+x 



minus [x] 



- x 



difference [x;y] 



This function has for its value 
the numeric difference between its 
arguments . 



addl[x] 
subl[x] 



x + 1 



x - 1 



times [x 1 ;x 2 ; . . . ;x ] Returns an integer equal to the 

product of x, ,x OJ ...x 

—1 ' —2 — n 



quotient [x;y] 



Greatest integer in quotient x/y 
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remainder [x;y] 



This function computes the number 
theoretic remainder for fixed- 
point numbers. 



divide[x;y] 



This function yields a dotted pair 
whose first member is quotient [x;y] 
and whose second member is 
remainder[x;y ] . 



numberp[x] 



x if x is a number; NIL otherwise 
This function works for floating 
point numbers as well as integers 



greaterp[x;y ] 



T if x>y; NIL otherwise 



lessp[x;y] 
zerop[x] 



T if x<y; NIL otherwise 



T if x is zero; NIL otherwise 



minusp[x] 



T if x is negative; NIL otherwise 



logand[x; . . . ;z] 



This function takes the logical 
and of all of its argument, and re- 
turn this value as an integer. 



logor[x; . . . ;z] 



This function takes the logical 
or of all of its arguments, and 
return this value as an integer. 



logxor[x 1 ;. . . ;x R ] 



Logical exclusive or of x, , . . . ,x 
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lsh[n;s] 



Performs an arithmetic left 
shift of s>o on n. Equivalent 
to n * 2 s . 



rsh[n;s] 



lrsh[x;n] 



Performs an arithmetic shift of 



s^o on n. Equivalent to n * 2 

Performs a logical right shift 
of x by n >0 places. 



-s 



abs[x] 
rand[m a n] 



Returns absolute value of x- 

Returns a random integer r, 
m>r>n. Uniformly distributed 

in the range m<r<n. 
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Floating Point Arithmetic 

The floating point arithmetic functions available in BBN LISP are 
fplus, f minus , f times , fquotient , and fgtp . They will accept 
mixed arguments, i.e. integer or floating point. Just as the 
integer-type functions fix any floating arguments before perfor- 
ming their computation, the floating-type functions float 
any fixed arguments before performing a computation. Thus the 
result of a floating point function is guaranteed to be a floating 
point number. 

The functions specifically related to floating £>oint are: 

fgtp[x;y] Floating greaterp ; compares by 

subtraction 

fix[x] Returns integer part of x 

fixp[x] Returns T if x is an integer, 

NIL otherwise. 

float [x] Produces floating number 

floatp[x] Returns T if x is a floating 

point number, NIL otherwise 

fminus[x] Negative of x 

fltfmt[x] Output format control; x is 

defined as the time-sharing system 
formatting of floating point output 

LISP normally operates with 
fltfmt[0]. Another useful format 
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is 3DDWW000Q, where DD is the number 
of digits following the decimal 
point, and WW the total field width. 

Thus with fltfmt[30205000Q], 
.62400000E+2 will be typed as 62.40 
.38000000E-1 will be typed as 0.04 

Numbers outside this range will be 
typed with E notation. 



fplus[x 1 ;x 2 ;. . . ;x n ] 



See time-sharing manual for complete 
description of floating formats. 

Returns the sum of its arguments 



fquotient[x;y] 



Returns x/y 



ftimes[x 1 ;x 2 ;. . . ;x n ] Product of its arguments 



expt[m,n] 



Returns as floating point number the 
value of m to nth power, m and n 
may be positive, negative, fixed or 
floating point numbers except that 
if m is negative and n fractional 
an error occurs. 



log[x] 



value is natural logarithm of x as 
a floating point number, x can be 
integer or floating point. 



antilog[x] 



value is floating point number whose 
logarithm is x. x can be integer 
or floating point. 
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sineCtheta] Truncates theta to nearest 5 

degrees and returns sine of theta 
as floating point number. Uses 
table look-up. 

cosine[theta] sine[theta+90] 



Equal and eqp will compare two floating point numbers for equality, 
and will float an integer to compare it to a floating point number. 
Eq when compiled is an open 24 bit compare which usually won't 
work for arithmetic comparisons. Equal uses eqp . 
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SECTION XIV 

INPUT/OUTPUT FUNCTIONS 

Opening and Closing Files 

All input (output) functions in BBN LISP can specify their source 
(destination) file with an optional extra argument which is the 
name of the file. This file must be opened as specified below. 
If the extra argument is not given (has value NIL), the file 
specified as "primary" for input (output) is used. Normally 
these are both T for teletype input and output. However, the 
primary input (output) file may be changed by 

input [name] Sets name to the primary input 

file. Its value is the name of 
the old primary input file. If 
name=NIL, value is current 
primary input file which is not 
changed. 

output [name] Same as input except operates on 

primary output file. 

Any file which Is made primary must have been previously opened 
for input (output). 

The user may have a maximum of 3 files open simultaneously, in 
addition to the teletype input and output files, and the output 
file NOTHING. 
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The three basic file manipulation operations are: 



infile[name] 



Opens for input the file named 
name and sets it as the primary 
input file. The value of infile 
is the name of the previous pri- 
mary input file. 



out file [name ; type ] 



Opens for output the file name , 
which is set to type type if type 
is not NIL, and otherwise to 
type 3, symbolic. Its value is 
the previous primary output file. 
It sets the standard (primary) 
output file to name . 



closef [x] 



Closes the named file. If x is 
NIL, it attempts to close the 
standard input file if other than 
teletype. Failing that, it attempts 
to close the standard output file 
if other than teletype. Failing 
either, it returns NIL. If it 
closes any file, it returns the 
name of that file. If it closes 
either of the standard files, it 
resets that standard file to 
teletype. 



openp[x] 



Returns NIL if x is not an open 
file, returns x if x is an open 
file. 
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Input/Output Transmission 

Most of the functions described below have an (optional) argument 
file which specifies the name of the file on which the operation is 
to take place. If that argument is NIL, the primary file will 
be used.* 



Note: in all 9^0 files, end-of-line is indicated by the characters 
carriage-return and line-feed in that order. Unless otherwise 
stated, carriage-return appearing in the description of an output 
function means carriage-return and line feed. 

On input from files, LISP will skip all line-feeds which immediately 
follow carriage-returns. On input from teletype, LISP will echo 
a line-feed whenever a carriage-return is typed. 

The following functions perform output : 

prinl[x, file] prints x on file 

prin2[x, file] prints x with double quote marks 

inserted where required for it to 
read back in properly 

Both PPiftl and prin2 print lists as well as atoms; neither print 
a carriage return upon termination; both have value x» prinl is 
usually used only for explicitly printing formatting characters, 
e.g. (PRIN1 (QUOTE ".")) might be used to print a period at the 
end of a sentence. prin2 is used for printing S-expressions 
which can then be read back into LISP with read i.e. atoms con- 
taining the regular LISP formatting characters in their print 
names will be printed with surrounding double-quote marks. If 
radix=8, prin2 puts a Q after numbers but prinl does not. 



file is used for tutorial purposes only. The arguments to all 
subrs, which includes prinl , prin2 etc., are u, v, and w, as 
described in arglist , p~! 87*5 . 
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prin3 [x, file] Prints x using double quotes for 

separation and break characters 
specified by setbrk and setsepr ; 
p. 11.7.- 

print [x, file] Prints the S-expression x using 

p_rin2; followed by a carriage- 
return linefeed. Its value is x. 

If any print function is given an atom containing a lower case char- 
acter, £, and the output file is the teletype character will print 
as %C* Similarly, control characters print as &C on the teletype. 
For all files, unboxed numbers print as #N, where N is the octal 
representation. (See p. 10.5). 

spaces [n, file] Produces n spaces; its value is 

NIL 

terpriLfile] Produces a carriage return; its value 

is NIL 

xcp d Produces a carriage return without 



a line feed; for teletype only; its 
value is NIL. Note: this carriage 
return is not detected by position. 

The print functions print , prinl , prin2 , and prin3 are all affect- 
ed by a level parameter set by 

printlevel[n] Sets print level to n, value is old 

setting. Initial value is 100000. 



* 



The line printer will print lower-case characters as lower-case 
characters. If the file is printed on the teletype, e.g. by 
the copy command, lower-case are printed as upper-case. 
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The variable_n_ controls the number of unpaired left parentheses 
which will be printed before any list will be printed as &. 

Suppose x = (A (B C (D (E F) G) H) K) 
Then if n = 2, print[x] would print 

(A (B C & H) K) 
and if n = 3, 

(A (B C (D & G) H) K) 
and if n = 0, it prints as just 

& 

If n is negative, action is similar except that a carriage return 
is inserted between all occurrences of right paren followed by 
left paren. The value of printlevel[n] is the old parameter 
setting. 

In order to change the level dynamically, while the system is 
printing at you, you can type control-P followed by a number, 
i.e. a string of digits, followed by a period or exclamation 
point. The print level will immediately be set to this number 
for this printout. If the print routine is currently deeper 
than the new level, all unfinished lists above that level will 
be terminated by " — )". Thus, if a circular or long list of 
atoms, is being printed out, typing in 

P c 

will cause the list to be terminated. If a period was used to 
terminate the number, level will be returned to its previous 
setting after this printout. If an exclamation point was used, 
the printlevel is changed permanently. This setting effects 
both print and printx which is the name of the printing function 
called by evalquote . 

Note: printlevel only affects teletype output. Output to all 
other files acts as though level is infinite. 
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Input Functions 



read [file; fig] 



Reads one S-expression from file . 
Atoms are delimited by parentheses, 
brackets, spaces, carriage returns. 
To input an atom which contains one 
of these syntactic delimiters en- 
close the atom in double quotes; 
e.g., "A,B,( ] C." A double quote 
immediately following the first 
double quote will be considered part 
of the print name, not as a termina- 
tor. To have a double quote internal 
to a quoted print name, use three 
double quotes; e.g. »'('""») a" will 
prinl as ( M )A, and "a" 1111 " as A."- If 
fig = T, then read will not count 
parens. 



readx[file;flg] 



Read program used by evalquote; same 
as read. 



rdflx[x] 



If x is NIL this function will try to 
read one S-expression with read[TJ; 
i.e. from teletype. If no error occur- 
red in reading, it will return with 
list of the S-expression that was read. 
If an error occurs in reading, it re- 
turns with MIL. If x is not NIL, it 
will attempt to read an S-expression 
and gets an error, it will print out 
x. In this case it returns with the 
S-expression itself (not list of the 
S-expression) . 
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ratom[file;flg] 



ratoms[a,file] 



setsepr[x] 
setbrk[x] 



Reads in one atom from file. Separation 
of atoms is defined by tables set by 
setsepr and setbrk, if fig = NIL. If 
fig = T, ratom uses the LISP tables. 

Calls ratom repeatedly until atom a 
is read. Returns a list of atoms 
read not including a. 

Sets sep arator characters 

Sets break characters 

Both setsepr and setbrk are of type 
EXPR*. Arguments are octal numbers 
which are ASCII codes for teletype 
characters, e.g., 155q for carriage 
return. 

Characters specified by setbrk will 
delimit atoms, and be returned as 
separate atoms themselves by ratom . 
Characters specified by setsepr will 
be ignored and serve only to separate 
atoms. Read does not use ratom , 
but if it did, space (Oq), and car- 
riage return (155q) would be separator 
characters; and left paren (lOq), 
right paren (llq), left bracket (73q), 
right bracket (75q), double quote (2q), 
and period (l6q) would be break 
characters. 
Thus 

setsepr[Oq 155q] 

setbrk[10q llq 73q 75q 2q l6q] 
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setseprc[x] 



setbrkc[x] 



setlsepr[u] 
setlbrk[u] 



ratest[x] 



would set up these characteristics. 
The value of setsepr and of setbrk 
is NIL. 

Same as setsepr except that the 
arguments should be single character 
atoms. 

Same as setbrk except that the arguments 
should be single character atoms. 
Use setlsepr , setlbrk . 

If u = NIL causes all separator 
(break) characters to be cleared. If 
u is a single character atom or a 
numeric code for a character, this 
character is added to the set of 
separator (break) characters. Returns 
T if this character was previously 
a separator (break) character, NIL 
otherwise. Error 10, "illegal argu- 
ment" occurs if number is out of 
range, or atom is not character atom. 

Performs three functions depending on 
setting of x. 

If x = T ratest returns indicator 
which is: 

T if a separator was encountered 
immediately prior to last atom 
read by ratom . 

NIL if there was no separator 
between last two atoms returned 
by ratom. 



14.8 



If x = NIL it returns an indicator 
which is: 

T if last atom returned by 
ratom was a break character. 

If x = 1 then it returns: 

T if last atom read contained 
double quotes (on READ or (RATOM 
x T)) NIL otherwise. 

readc[file ; fig] Reads the next character. Allows 

paren counting and line buffering 
if fig = T. 

unreadc[n,f ile] If n is the code for a single character 

or a single character atom, it will 
be placed at the beginning of the 
input buffer and thus taken as the 
next character read. May not be done 
two or more times without intervening 
read . 
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Input/Output Control Functions 

These functions perform a variety of operations on the state of 
files. 

clearbuf C] Clears the input buffer of TTY. 

radix[u;v] Sets output radix to u and sign in- 

dicator to v. If u is T, negative 
numbers will print as sign and 23 bit 
value (normal) . If u is NIL, all 
numbers print as 24 bit unsigned 
integers. Returns previous setting. 

control[u;v] If v is not NIL, the system echo 

table is set to v, which is the 2nd 
argument to BRS 12(A REGISTER). 

The value of u sets modes for reading 
with ratom as follows: 

u = T Eliminates LISP'S normal line buffer- 

ing, automatic detection of control-A 
and control-Q as line-editing char- 
acters on the TTY and paren counting. 

u = NIL Restores line buffering (normal). 

u = -1 Restores line buffering and causes 

characters in current line not yet 
read to be reprocessed by paren 
counter and line buffer handler. 

u = Eliminates the echo of the character 

being deleted by control-A. 

u = 1 Restores the echo (normal) . Value is 

old setting. 
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linelength[n] 



position[ ] 



readp[] 



Sets the length of the print line for 
all files. The value is the former 
setting of the line length. 

Gives the character position on the 
print line. No guarantees are made 
about its meaningfulness if output is 
being done intermittently to more 
than one file. 

Gives T if there is something in the 
output buffer (either the TSS input 
buffer or LISP'S line buffer) and NIL 
otherwise . 



Special Functions 



sysout[name] 



sysin[name] 



sysget[name] 



Saves the user's private memory on the 
file name . The value of sysout is the 
number of words required. Note: 
whenever the LISP system is reassembled, 
old sysout files are no longer readable. 

Restores the state of LISP from a 
sysout file. Value of sysin is the 
number of private pages (256 words) 
read. If sysin returns NIL or INCOM- 
PATIBLE, it was unable to read the 
file name . 

Initializes LISP and then does 
sysin[name]. If name = T, just 
initializes LISP. 
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rbin[file] 



wbin(w;file] 



ginfn[name] 
goutfn[name] 



ginfx[name] 
goutfx[name] 



filetype[name] 



copyfile[from;to] 



delfile[file] 



Reads one 9^0 24 bit word from file , 
the specified file. This function 
returns the word as a number. 

Writes one word, w, on file specified 
by file . W must be a number. 

Obtains system 's, file number for 
previously opened input (output) file. 
Useful for performing direct I/O from 
hand-coded function. Cannot be used 
as file argument for I/O functions. 
See ginfx , goutfx . 

These functions obtain the LISP file 
index for the previously opened input 
(output) file. Can be used as argu- 
ment to I/O SUBR in place of file 
name. It is somewhat faster especially 
in case of repeated calls e.g. READC, 
RATOM, PRIN1, etc. 

Obtains number indicating type for 
previously opened input or output file. 

copies file from to file to, e.g., 
COPYFILE[/FOO/; "LINE PRINTER"]. 
Value is to . 

delete file . Value is file if found, 
otherwise NIL. 



renamefile[old,new] renames old to new . Value is OLD-FILE 

if new is an old file, NEW-FILE if new 
is a new file, or NIL if unsuccessful. 
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Symbolic File Input 



load[x;flg;p] 



load is a function which reads 
successive S-expressions from file 
x and evaluates each as it is read, 
until it reads either NIL, or the 
single atom STOP , followed by a 
carriage return, at which point it 
returns the value NIL. 



If p=T, load prints the value of 
each S-expression; otherwise it 
does not. fig affects the treatment of 
expressions beginning with deflneq : 
if flg=NIL, dfnf lg is bound to T and 
the expression evaluated. If flg =T, 
dfnflg is bound to NIL and the expression 
evaluated. (This reversal is used so 
that with the normal usage of load , 
with only the first argument 
specified, defineq will operate as 
though dfnflg were T, its normal 
setting.) If flg= PROP, defineq is 
not called. Instead, the function 
definitions are stored on the 
property lists. 

Thus if the function definitions 
for a particular file were all 
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compiled, and one wished to edit a 
function definition, and make a new 
copy of the file containing it, 
without disturbing the compiled 
definitions, one would perform 
load[file;PROP], followed by 
editf[fn], since editf automatically 
goes to the property list if the 
function definition cannot be 
edited, followed by 

prettydef [fns;file], since prettydef 
automatically goes to the property 
list if the function definition 
cannot be prettyprinted. 



readfile[v;x] 



reads successive S-expressions from 
file x until the single atom STOP 
is read, makes a list of these 
S-expressions, and sets v to this 
list. Value is x. 



Symbolic File Output 
writefile[v;x] 



writes successive S-expressions from 
v onto file x. If v is atomic, its 
value is used. If x is not open, 
it is opened and the date printed out 
When v is finished, a STOP is printed 
on x and it is closed. Value is x. 
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prettyprint[x] 



If x is an atom it will be evaluated 
to yield a list of functions. The 
definitions of the functions will 
be printed in a pretty format. If 
x is a list, it is used directly 
as the list of functions. 



Example: 



(FACTORIAL 
(LAMBDA (N) 
(COND 

( (ZEROP N) 

1) 
(T (TIMES N (FACTORIAL (SUB1 N))))))) 

Note: prettyprint will operate correctly on functions that are 
broken , broken-in , advised , or have been compiled with 
their definitions saved on their property lists - 
it prints the original, pristine definition. 

A facility for documenting LIS P functions is provided in prettyprint . 
Any S-expression beginning with * is interpreted as a comment and 
printed in the right margin.* Example: 



(FACTORIAL 
(LAMBDA (N) 
(COND 

( (ZEROP N) 

1) 
(T 



(* COMPUTES Nl) 

(* 01=1) 

(* RECURSIVE DEFINITION: 
N!=N*N*1 1 ) 



(TIMES N (FACTORIAL (SUB1 N))))))) 



These comments actually form a part of the function definition. 
Accordingly, * is defined as an NLAMBDA NONSPREAD function that 
returns its argument, i.e. it is equivalent to QUOTE. When run- 
ning an interpreted function, s is entered the same as any other 



* Comments begin in column firstcol , initially set to 50, and end 
in column lastcol , initially set to 7^. 
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LISP function. Therefore, comments should only be placed where 
they will not harm the computation. For example, writing 
(TIMES N(FACTORIAL (SUB1 N) ) (* RECURSIVE DEFINITION)) in the 
above function would cause an error when TIMES attempted to 
multiply N, N-l ! , and RECURSIVE. 

For compilation purposes, * is defined as a macro which compiles 
into no instructions. Thus, if you compile a function with 
comments, and load the compiled definition into another system, 
the extra atom and list structures storage required by the com- 
ments will be eliminated. This is the way the comment feature is 
intended to be used. 



endfile[x] 



printdefCe] ' 



Prints STOP on and closes the file 
specified by x. 

prints the expression e on the 
primary output file in a pretty 
format, i.e. , prettyprint does 
printdef[getd[fn]] after appro- 
priately setting output files, 
printlevel, etc. 

prettydef[prtyx;prtyy;prtyl] This function is used for the 

creation of files containing sys- 
tems of functions. 

The arguments are interpreted as follows : 



prtyx 

(first argument) 



If a list, it is treated as a list 
of function names. If prty x is an 
atom, it should have as a binding 
the list of functions for prettydef 
The functions on the list are 
prettyprint ed surrounded by a 
(DEFINEQ ...) so that they can be 
loaded with load. In addition, a 
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prtyy 

(second argument) 



prtyl 

(third argument) 



frpaqq will be written which saves 
the list of functions on the named 
atom, and a print will be written 
which informs the user of the named 
atom when the file is subsequently 
loaded. 

is the name of the file on which 
the output is to be written. The 
following options exist: 
file=NIL 

The standard output file is 
used as determined by the 
last setting of output . 
file=atom 

The file atom is opened if 
not already open, and becomes 
the standard output file. 
file=list 

Car of the list is assumed 
to be the file name and is 
opened if not already open. 
The standard output file is 
not changed in this case. 

is a list of commands, or if 
atomic, its value is used as a 
list of commands and an rpaaq is 
written which saves the list of 
commands on the named atom, and a 
print which informs the user of 
the named atom when the file is 
subsequently loaded, exactly as 
with the first argument. 
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These commands are used to save 
on the output file top level bindings 
of variables, property lists of atoms, 
miscellaneous LISP forms to be 
evaluated upon loading, arrays, and 
advised functions. It also provides 
for evaluation of forms at output 
time. 

The interpretation of each command 
in the command list is as follows: 

1. if STOP, the file is closed. 

2. if atomic, an RPAQQ is written 
which will restore the top 
level binding of this atom then 
the file is loaded. 

3. if of the form 

(PROP property atoml . . . atomn) 

for each atom following property , 
an appropriate DEPLIST will be 
written which will restore the 
property for each corresponding 
atoml . . . atomn when file is 
loaded. If property=ALL, the 
entire property list will be 
written with an RPLACD. If property 
is a list, DEFLISTs will be written 
for each property. 

2|. if the form (ARRAY ...), each 

atom following ARRAY should have 
an array as its value, and an 
appropriate expression will be 
written which will set the atom 
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to an array of exactly the same 
size, type, and contents upon 
loading. 

5. If of the form (P ), each 

S-expression following P will 
be printed on the output file, 
and consequently evaluated upon 
loading. 

6. If of the form (E ....), each 
form following E will be evalu- 
ated immediately, i.e., while 
prettyprint is operating. 

7. If of the form (ADVISE fnl ... fnm) 
an appropriate expression will be 
written for each of the m func- 
tions which will upon loading 
allow the user to reinstate the 
advice using the function 
READVISE . 

8. If of the form (FNS fnl ... fnm), 
a defineq is written with the 
definitions of fnl ... fnm, 
exactly as though (fnl ... fnm) 
where the first argument to 
prettydef , e.g. suppose the user 
wanted to set some variables or 
perform some computations in a file 
before defining functions, for example, 
do a minfs, he would then write the 
definitions using this option in-, 
stead of using the first argument 

to prettydef . 
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9. If of the form 

(COMMANDS coml ... comn), each 
of the commands coml . . . comn 
will be Interpreted as one of 
the above eight command types. 

In each of the nine commands described above, if the atom "*" 
follows the command type, the form following the *, i.e., caddr , 
is evaluated and its value used in executing the option, e.g., 
(FNS * FOOFNS), (PROP * FOOPROPS). Note that in the latter case, 
(CAR FOOPROPS) will be the property (ies) to be saved, and 
(CDR FOOPROPS) the list of atoms for which this property is to 
.be saved. 

Note that (COMMANDS * form) provides a way of computing what 
should be done by prettydef . 

Example: 

SET(FOOFNS (F001 F002.F003)) 

SET(FOOVARS(FIE (PROP MACRO F001 F002) (P (MOVD (QUOTE F001) 
(QUOTE FIE1))) STOP) 

PRETTYDEF (FOOFNS /F00/ FOOVARS) 
would create a file /F00/ containing 

1. A message which prints the time and date the file was made 

(done automatically) 

2. DEFINEQ followed by the definitions of FOOl, F002, and F003 

3. (PRINT (QUOTE FOOFNS)) 

4. (RPAQQ FOOFNS (FOOl F002 F003)) 

5. (PRINT (QUOTE FOOVARS)) 

6. (RPAQQ FOOVARS (FIE ... STOP) 

7. (RPAQQ FIE value of fie ) 

8. (DEFLIST (QU0TE((F001 PROPERTY) (F002 PROPERTY))) (QUOTE MACRO)) 

9. (MOVD (QUOTE FOOl) (QUOTE FIE1)) 
10. STOP 
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printfns[x] 



printdate[ ] 



tab [pos, minspaces ,fn e ] 



x is a list of functions, printfns 
prints DEFINEQ and prettyprints the 
functions. Used by prettydef , i.e. 
command (FNS * F00) is equivalent 
to command (E (PRINTFNS POO)). 

prints the expression at beginning 
of prettydefed files that types 
date upon loading. 

performs appropriate number of 
spaces to move to position pos . 
If position + minspaces is greater 
than p_os_, does terpri and then 
spaces [pos]. If minspaces not 
given, 1 is used. 



makefile[file;flg] 



does prettydef[fileFNS;/nfile/; fileVARS] 
where /nfile/ is first unused file, 
e.g., if user's file directory con- 
tains /1F00/ and /2F00/ makefile[FOO] 
does prettydef [F00FNS;/3F00/ FOOVARS]. 
If fileVARS is unbound atom, makefile 
uses (STOP). 

If fl S = T > file is also listed using 
listfile . 



listfile[files] 



Lists each file in files on line 
printer using utility . Value is 
files. 
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SECTION XV 

DEBUGGING AND ERROR HANDLING 

Debugging Facilities 

Debugging a collection of LISP functions involves isolating problems 
within particular functions and/or determining when and where incor- 
rect data is being generated and transmitted. In the BBN-LISP system, 
there are three facilities which allow the user to (temporarily) 
modify selected function definitions so that he can follow the flow 
of control in his programs, and obtain this debugging information. 
These three facilities together are called the break package, All 
three redefine functions in terms of a system function, breakl, 
described below. 

Break modifies the definition of fn so that if a break condition 
(defined by the user) is satisfied, the process is halted tempo- 
rarily on a call to fn. The user can then interrogate the state 
of the machine, perform any computations, and continue or return 
from the call. 

Trace modifies a definition of a function fn so that whenever fn is 

called, its arguments (or some other values specified by the user) 
are printed. When the value of fn is computed it is printed also. 
(Trace is a special case of break ) . 

Breakin allows the user to insert a breakpoint inside an expression 
defining a function. When the breakpoint is reached and if a break 
condition (defined by the user) is satisfied, a temporary halt 
occurs and the user can again investigate the state of the 
computation. 

The following two examples illustrate these facilities. In the 
first example, the user traces the function FACTORIAL. TRACE 
redefines FACTORIAL so that it calls BREAK1 in such a way that it 
prints some information, in this case the arguments and value of 
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P RETT YPRINTC (FACTORIAL) ) 

(FACTORIAL 
(LAMBDA (iM) 
(COND 

((ZEROP N> 

L) 
(T (TIMES N (FACTORIAL (SU31 iM ))).))■> ) 
NIL 

-TRACE(FACTORIAL) 
(FACTORIAL) 
-FACTORIAL (5) 

FACTORIAL: 
N = 5 



FACTORIAL: 
■M = 4 



FACTORIAL: 
N = 3 



FACTORIAL 
N = 2 



FACTORIAL 
N = 1 



FACTORIAL: 

N s 



ERROR 

CL IS UNBOUND ATOM) 

( FACTORIAL BROKEN) 

: N 



: RETURN 1 

FACTORIAL = 1 

FACTORIAL = 1 
FACTORIAL = 2 
FACTORIAL = 6 
FACTORIAL = 24 
FACTORIAL = 123 
1 20 
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PRETTYPRINTC (FACTORIAL) ) 

(FACTORIAL 
(LAMBDA (N) 
(PROG (M) 

(SE'IO Ml) 
LOOP(COND 

((ZEROP N) 

(RETURN M))) 
(SETQ M (TIMES M N)) 
(SETQ N (SUB1 N)) 
(GO LOOP) 
))) 
NIL 

-BREAKIN(FACTORIAL (AFTER LOOP) (LESSP N 2)) 

SEARCHING... 

FACTORIAL 

-FACTORIALS) 

( (FACTORIAL) BROKEN) 
: NN 

ERROR 

( NN IS UNBOUND ATOM^ 

(FACTORIAL BROKEN AFTER LOOP) 

: N 

1 

: M 

1 20 

: OK 

( FACTORIAL) 

( (FACTORIAL) BROKEN) 

: N 



: OK 

(FACTORIAL) 

1 20 
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FACTORIAL, and then goes on with the computation. When an error 
occurs on the fifth recursion, BREAK1 reverts to interactive mode, 
and a full break occurs. The situation is then the same as though 
the user had originally performed BREAK (FACTORIAL) instead of 
TRACE ( FACTORIAL) , and the user can evaluate various LISP forms and 
direct the course of the computation. In this case, the user 
examines the variable N, and instructs BREAK1 to return 1 as the 
value of this call to FACTORIAL. The rest of the tracing proceeds 
without incident. The user would then presumably edit FACTORIAL 
to change L to 1. In the second example, the user has constructed 
a non-recursive definition of FACTORIAL. He uses BREAKIN to 
insert a call to BREAK1 just after the PROG label LOOP. This 
break is to occur only on the last two iterations, i.e., when N 
is less than 2. When the break occurs, the user looks at the 
value of N, mistakenly typing NN. However, the break is maintained 
and no damage is done. After examining N and M, the user allows 
the computation to continue by typing OK. A second break occurs 
after the next iteration, this time with N=0. When this break is 
released, the function FACTORIAL returns its value of 120. 
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Breakl 

The basic function of the break package is breakl . It allows the 
user to interrogate the state of the world and to affect the course 
of the computation, breakl uses the ready character ":" to in- 
dicate it is ready to accept forms for evaluation (by eval ) . The 
user may type in forms to eval and, under heavy errorset protection, 
see the value of the computations. In addition, he has the follow- 
ing options that are specifically recognized by breakl: 

GO Releases the break and allows 

the computation to proceed. 
BREAK1 evaluates BRKEXP, its 
first argument, prints the value, 
and returns it as the value of 
the break. BRKEXP is set up by 
the function that created the call 
to BREAKl. For BREAK or TRACE, 
BRKEXP is (dummy ARG1 ARG2 ... 
ARGN), where dummy has the original 
definition of the function being 
broken and ARG1, ARG2, ... ARGN 
are its arguments. BRKEXP is NIL 
for BREAKIN using BEFORE or AFTER, 
and the indicated expression for 
BREAKIN AROUND. 

OK Same as GO except the value of 

BRKEXP not printed. 

EVAL Same as GO or OK except that the 

break is maintained after the 
evaluation. The user can then 
interrogate the value which is 
bound on the variable VALUE, and 
continue with the break. Typing 
GO or OK following EVAL will not 
cause reevaluation, but another 
EVAL will. This is a useful option 
when the user is not sure whether 
or not the break will produce the 
correct value and wishes to be able 
to do something about it if it is 
wrong. 
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RETURN form The value of form is returned as 

the value of the break. For 
example, one might use the EVAL 
command and follow this with 
RETURN (REVERSE VALUE). 

t Calls error and aborts the break. 

i.e. makes it "go away" without 
returning a value. This is a use- 
ful way to unwind to a higher level 
break. All other errors, includ- 
ing those encountered while exe- 
cuting the GO, OK, EVAL, and 
RETURN option, maintain the break. 

Once a break occurs, control of the computation reverts to the 
user. The computation does not proceed without a specific instruc- 
tion from the user. In most cases the user will simply check the 
values of certain key variables, and allow the computation to 
proceed. If he is not interested in the value of the break, he 
probably will use the OK command, and BREAK1 will "quietly go 
away." If he is interested in seeing the value, but fairly cer- 
tain that it will be correct, he may use the GO command. If he 
wairts to see the value of the break, but still have the option of 
further interaction with BREAK1, he will use the EVAL command, 
after which he can examine the variable VALUE. By means of the 
RETURN command, he can force BREAK1 to return an appropriate 
value, even when his function is still "buggy." This can be 
useful in localizing a problem in a large program. If substitu- 
ting the omniscient user for a faulty function corrects the bug, 
then the problem has been isolated. 

BREAK1 puts all of the power of LISP at the users command. For 
example, he can insert new breaks on subordinate functions simply 
by typing: 

(BREAK functionl function2) 
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or he can remove old breaks and traces if too much information 
is being supplied: 

(UNBREAK function3 function** ) 

He can edit functions, including the One currently broken: 

(EDITP function ) 

For example, the user might type EVAL, see that the value was 
incorrect, call the editor, repair the bug, and type EVAL again, 
all without leaving the break. 

Similarly, the user can prettyprint functions, define new functions 
or redefine old ones, etc., load a file, compile functions, time a 
computation, etc. In short, anything that he can do at the top 
level EVALQUOTE can be done while inside of the break. In addition, 
the user can examine the pushdown list, via the functions described 
in section 12, and even force a return back to some higher function 
via the function ret from . 

Brkcoms 

The fourth argument to breakl is brkcoms , a list of break commands 
that breakl interprets and executes exactly as though they were 
teletype input. One can think of brkcoms as another input file 
which always has priority over the teletype. Whenever brkcoms= NIL, 
breakl reads its next command from the teletype. Whenever brkcoms 
is not NIL, breakl takes as its next command car [brkcoms] and sets 
brkcoms to cdrCbrkcoms] . For example, suppose the user wished to 
see the value of the variable x after a function was evaluated. 
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He would set up a break with brkcoms =(EVAL (PRINT X) OK), which 
would have the desired effect. The function trace uses brkcoms : 
it sets up a break with two commands; the first one prints the 
arguments of the function, or whatever the user specifies, and the 
second is the command GO, which causes the function to be evaluated 
and its value printed. 

Note: if brkcoms is not NIL, the value of a break command is not 
printed. If you desire to see a value, you must print it yourself, 
as in the above example with the command (PRINT X). 

Note: Whenever an error occurs, brkcoms is set to NIL, and a full 
interactive break occurs. 

Breakmacros 

Breakl specifically recognizes the five atomic commands +, GO, 
RETURN, EVAL, and OK. Whenever an atomic command is given breakl 
that it does not recognize, either via brkcoms or the teletype, 
it searches the list breakmacros for the command. The form of 
breakmacros is ( ... (macro commandl command2 . . . commandn) . . . ) . 
If the command is defined as a macro, breakl simply appends its 
definition, which is a sequence of commands, to the front of 
brkcoms, and goes on. If the command is not contained in 
breakmacros, it is evaluated as before. 
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The following breakmacros are currently defined: 

?= if from brkcoms , looks at next 

command on brkcoms and prints the 
value of each member of that list. 
For example, if brkcoms were 
(EVAL ?= (X Y) OK), the user would 
see 

( function BROKEN) 
function EVALUATED 
X= value of x 
Y= value of y 
function 

If the next command on brkcoms 
is T, ?= operates on all of the 
arguments of the broken function, 
i.e. if the arguments of the broken 
function are X and Y, ?= T is 
equivalent to ?= (X Y). ?= is used by 
trace . 

?= typed in by user is equivalent 
to the commands ?= and T on brkcoms , 
i.e. the names and values of the 
arguments to the broken function 
are printed. 

!EVAL function is first unbroken, then 

evaluated, and then rebroken. Very 
useful for dealing with recursive 
functions. 

tOK Function is first unbroken, eval- 

uated, rebroken, and then exited, 
i.e. !0K is defined as !EVAL fol- 
lowed by OK. 

!G0 Function is first unbroken, eval- 

uated, rebroken, and exited with 
value typed, i.e. JEVAL followed 
by GO. 
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ARGS the names of the arguments of the 

broken function are printed. 

%A evaluates and prints the value of 

the atom a, (lower-case A), see p. 12.4. 

Bell (Control-G) reverses the setting of brkevqflg , 

and prints new value, i.e. does 
(PRINT (SETQ BRKEVQPLG (NULL BRKEVQFLG))) 

If brkevqflg= NIL, its normal setting, breakl operates in 
eval mode, uses : as its ready character and expects one input 
which it evaluates using eval (except if input" is one of the 
five commands + , GO, EVAL, OK or RETURN or a breakmacro). 

If brkevqflg =T, breakl operates in evalquote mode, its ready 
character is «-, and it then expects two inputs, a function and 
its arguments, which it gives to evalquote . However, 
the five regular commands as well as any breakmacros are not 
affected by the setting of brkevqflg and will always be recog- 
nized, evalquote mode is useful if you have a lot of express- 
ions to evaluate that would otherwise have to be quoted, e.g. 

:(PUT (QUOTE F00) (QUOTE PIE) (QUOTE ...)) 

vs 

♦PIT (POO PIE ...) 

in evalquote mode . 

BT Prints a backtrace of function names 

only . If BT is followed by a function 
name, on the same line of input, the 
backtrace starts from the last occur- 
rence of that function, e.g. 

BT F00 

prints POO and all functions entered 
above it in reverse chronological 
order. A number (position on the 
push list) can be used instead of 
a function name. Otherwise back- 
trace starts from the current 
position except that calls to 
error, faulteval, breakl, etc., 
are initially skipped. 
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BTV Prints a backtrace of function names 

with variables. If followed by a 
number on the same line of input, 
printlevel is set to that number 
during the backtrace only, e.g. 

BTV 2 

will print a backtrace with the values 
of all variables being printed to a 
depth of 2. If this number is not 
supplied, printlevel is set to 0_ for 
backtrace. In both cases printlevel 
is restored after backtrace, even if 
interrupted by a control-R. Note 
however, if the backtrace is aborted 
by a control-C, the printlevel will 
not have been restored. 
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Miscellaneous 

The fifth argument to breakl is brkfile, and determines the output 
file for breakl . If it is NIL, the teletype is used. However, 
brkfile can be used to dump diagnostics onto a disc file, or even 
onto the file NOTHING. If brkfile is not open, it is opened. If 
an error occurs, brkfile is set to NIL and all output goes to the 
teletype. 

brkx is a prog variable in breakl which is bound in breakl but not 
used. It is available for the user, to provide a local binding: for 
computations associated with breaks. 

Break Functions 

breakl[brkexp;brkwhen;brkfn;brkcoms;brkfile] 

is an nlambda . brkwhen determines 
whether a break is to occur. If 
its value is NIL, brkexp is evalu- 
ated and returned as the value of 
breakl . Otherwise a break occurs 
and an identifying message is 
printed using brkfn . Commands are 
then taken from brk corns or the 
teletype and interpreted. The 
commands GO, OK, RETURN, and + , 
are the only ways to leave 
breakl . The command EVAL causes 
brkexp to be evaluated, and saves 
the value on the prog variable 
value. Other commands can be 
defined for breakl via breakmacros. 
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break0[fn;when; corns; file] sets up a break on the function fn 

by redefining fn as a call to 
b r e ak 1 with the original definition 
of fn as brkexp ,and when , fn, corns, 
and file as brkwhen , brkfn, brkcoms 
and brkfile. Puts property BROKEN 
on property list of fn with value 
a gensym defined with the original 
definition. Adds fn to the list 
brokenfns . Value is fn. 

If fn is non-atomic and of the form 
(fnl IN fn2), breakO first calls a 
function which changes the name of 
fnl wherever it appears inside of 
fn2 to that of a new function, fnl- 
IN-fn2, which it initially defines 
as fnl . Then breakO proceeds to 
break on fnl-IN-fn2 exactly as des- 
cribed above. This procedure is use- 
ful for breaking on a function that 
is called from many places, but where 
one is only interested in the call 
from a specific function, e.g. 
(RPLACA IN POO), (PRINT IN FIE), etc. 
It is similar to breakin described 
below, but can be performed even when 
FN2 is compiled whereas breakin only 
works for interpreted functions. 

If fnl is not found in fn2, breakO 
returns the value (fnl NOT FOUND IN 
fn2). 
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If fnl is found in fn2, in addition 
to breaking fnl-IN-fn2 and adding 
fnl-IN-fn2 to the list brokenfns , 
breakO adds fnl to the property 
value for the property NAMESCHANGED 
on the property list of f n2 and 
adds the property ALIAS with value 
(fn2 . fnl) to the property list of 
fnl-IN-fn2. This will enable unbreak 
to recognize what changes have been 
made and restore the function fn2 to 
its original state. 

If fn is nonatomic and not of the 
above form, breakO is called for each 

member of fn using the same values 
for when , corns , and file specified 

in this call to breakO . This as- 
sociativity permits the user to 
specify complicated break conditions 
on several functions without retyping, 
e.g. 

breakO[(F001 (PRINT IN F002)), (NEQ X T) 
(EVAL ?= (Y Z) OK)] 

Associativity is also available for 
breaking in e.g. break0[ ( (PRINI PRINT) 
IN (POO PIE)),T] 

Value is list of individual values. 

break[x] is a nonspread nlambda . For each 

atomic argument, it performs 
break0T[atom;T]. For each list, it 
performs apply [BREAK0 3 list]. For 
example, 
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BREAK(F001 (F002 (GREATERP N 5) )) 

will establish breaks on FOOl and 
F002, the latter a conditional 
b r e ak . 

trace [x] is a nonspread n lamb da. For each 

atomic argument, it performs 
break0[atom;T; (TRACE ?= T GO)]* (see 
discussion of brk corns and break- 
macros in text). For each list, 
it performs 

break0[car [list ];T; list [TRACE, ?=, 
cdr[list],GO]]* 

For example, TRACE(F001 (F002 Y)) 
will cause both FOOl and F002 to 
be traced. All the arguments of 
FOOl will be printed; only the 
value of Y will be printed when 
F002 is entered. 

Note: the user can always call breakl himself to obtain combination 
of options of breakl not directly available with break and 
trace . These two functions merely provide convenient ways of 
calling break0, and will serve for most uses. 



(*) The flag TRACE is checked for in breakl and causes the 

message "function": to be printed instead of (function BROKEN). 
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breakin[fn, where, when, corns, file] 

breakin is an nlambda . Its last 
three arguments correspond to the 
last three arguments of breakO , 
except if when is NIL, T is used. 
where specifies where in the defi- 
nition of fn the call to breakl 
is to be inserted. There are three 
possibilities: (BEFORE ...), (AFTER 
. . .), or (AROUND .. .). " . . . " is 
used by the expanded editor's locate 
routine to find the correct point 
for the break. For example, (BEFORE 
COND) will insert a break before the 
first occurence of cond , and (AROUND 
(SETQ X — )) will break around the 
first place X is set. Note that 
specifications such as (AROUND ALL 
(SETQ X — )) for breaking around 
every place x is set, and (AROUND 
(SECOND (COND CONTAINING RETURN))) are 
perfectly acceptable. See p. 9.26- 
9. 40 for description of expanded 
editor. 

If fn is a compiled function, breakin 
returns UNBREAKABLE as its value. 

If fn is interpreted, breakin types 
SEARCHING... while it calls the 
editor. If the location specified 
by where is not found, breakin types 
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(NOT FOUND) and exits. If it is 
found, breakin adds the property 
BROKEN-IN with value to T to the 
property list of fn, and adds fn 
to the list brokenfns . 

Because of the operation of the UP 
command in the expanded editor, 
(BEFORE COND) and (BEFORE X) will 
both have the desired effect. The 
first will insert a break before 
the entire expression beginning 
with COND, the second before X it- 
self. A special check is made to 
avoid inserting a break in the 
wrong place when a variable may 
appear as car of an expression, as 
in the case of a cond or selectq, 
i.e. the X in (COND ... (X ..) ...) 
will not satisfy the locating routine 

Another special check is made to 
avoid inserting a break anywhere 
inside of an expression headed by 
any member of the list nobreaks , 
initialized to (GO QUOTE *), since 
this break would never be activated. 

It is possible to insert multiple 
break points, with a single call to 
breakin by using a list of the form 
( (BEFORE . . . ) . . (AROUND . . . ) ) for 
where. It is also possible to call 
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break or trace on a function which 
has been modified by breakin , and 
conversely to breakin a function 
which has been redefined by a call 
to break or trace . 

unbreak[x] unbreak is a non-spread n lamb da . 

It takes an indefinite number of 
functions modified by break , trace , 
or breakin and restores them to 
their original state by calling 
unbreakO . unbreak[] will unbreak 
all functions on brokenfns , a list 
that is updated by breakO and 
breakin . Value is list of values 
of unbreakO . 

unbreakO [fn] restores fn to its original state. 

If fn was not broken, value is 
(NOT BROKEN) and no changes 
are made. If fn was modified by 
breakin , unbreakin is called to 
edit it back to its original state. 
If fn was created from (fnl IN fn2), 
i.e. if it has a property ALIAS, 
the function in which fn appears 
is restored to its original state. 
All dummy functions that were 
created by the break are eliminated. 

Note: unbreakO[(fnl IN fn2] is 
allowed: unbreakO will operate on 
fnl-IN-fn2 instead. 
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unbreakin[fn] 



changename [ f n , from , t o ] 



virginfn[fn,flg] 



performs the appropriate editing 
operations to eliminate all changes 
made by breakin . fn may be either 
the name or definition of a function. 
Does not check to see if any changes 
were made. Value is fn. 

changes all occurrences of from to 
to in fn. fn may be compiled. 
Value is fn if from was found, 
otherwise NIL. Does not perform 
any modifications of property lists. 

is the function that knows how to 
restore functions to their original 
state regardless of any amount of 
breaks, breakins, advising, compil- 
ing and saving exprs, etc. It is 
used by prettyprint , define , and 
the compiler . If flg=NIL, as for 
prettyprint , it does not modify 
the definition of fn in the process 
of producing a "clean" version of 
the definition. If flg=T as for 
the compiler and define , it physically 
restores the function to its original 
state, and prints the changes it is 
making, e.g. F00 UNBROKEN, F00 UNADVIS- 
ED, etc. Value is the virgin function 
definition. 
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valv[x,fn,n] a useful form of evalv for inside 

of a break, valv is an nlambda . 
x is the name of a variable to be 
evaluated, using evalv, as of the 
nth occurrence of the function fn, 
i.e. nthfn[fn,n]. If n is NIL, 1 
is used. If fn is NIL, the last 
position used by valv is used (it 
is saved on the free variable 
vvnlast ) . For example, 

:(VALV X MATCH) 

value of X as of last call to MATCH 

:(VALV Y) 

value of Y as of last call to MATCH 
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Error Handling in LISP 

There are currently twenty four different error types in the 
BBN LISP system. These are discussed in greater detail below. 
However, by far the most common "error condition" in LISP pro- 
grams: unbound atoms and undefined functions, is not treated as 
an error at all, but handled in a special way by the BBN inter- 
preter. The basic difference between a bona fide error, and an 
unbound atom or undefined function, is that errors are detected 
after they occur, e.g. PDL OVERFLOW, NONXMEM, or else they are 
detected inside a low-level function ( a SUBR, SUBR* or FSUBR*), 
like plus or setq e.g. NUN-NUMERIC ARG, NON- ATOMIC ARG, ILLEGAL 
REGISTER COMMAND, whereas unbound atoms and undefined functions 
are detected by the interpreter when it attempts to evaluate a 
LISP form. Consequently, the system is in a better position to 
allow the user to correct unbound atom and undefined function 
error conditions than the more basic errors, although these too 
are "helpable" in the BBN LISP system. 
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Unbound atoms and undefined functions 

Whenever the interpreter encounters an atomic form with no binding 
on the push-down list, and whose value is the atom NOBIND,(*) the 
interpreter calls the function faulteval . Similarly, faulteval 
is called when a non-atomic form is encountered, car of which is 
not a function. (**) . The value returned by faulteval is used by 
the interpreter as the value of the form. faulteval is defined 
to print either UNBOUND ATOM or UNDEFINED CAR OF FORM, followed 
by the name of the atom or car of the form, and then to call 
breakl giving it as brkexp the offending form. Once inside the 
break, the user can set the atom, define the function, return a 
specified value for the form using the RETURN command, etc, or 
abort the break using the t command. If the break is exited 
with a value, the computation will proceed exactly as though no 
error had occurred. 

This call to breakl can be inhibited by setting to NIL the vari- 
able helpflag , which is initially set to T. In this case, faulteval 
instead calls the function error (p. 15.33). It is at this point that 
the unbound atom or undefined car of form actually becomes a LISP 
error. Similarly, error is called instead of breakl if the "error" 



(*) All atoms are initialized (when they are created by the 
read program) with their value cells (car of the atom) 
NOBIND, their function cells NIL, and their oronerfcv list-.* 
(cdr of the atom) NIL. 

(**) See Appendix 2 for complete description of BBN LISP interpreter, 



15.22 



occurs within helpdepth, initially set to 4, function calls from 
the top level evalquote or the last errorset (p. 15.33). In the 
example below, a break occurs when F000 is evaluated inside the 
map car , but not when typed in to e_. Of course, the user can set 
helpdepth to any value he wishes. For helpdepth= 0, breaks will 
always occur. 



-SETCFOO (1 2 3)) 

(12 3) 

-E (MAPCAR F000 (FUNCTION ADD1 ) ) 

UNBOUND ATOM F000 

( F000 BROKEN) 
: RETURN F00 
F000 =(12 3) 
(23 4) 
-E F000 

ERROR 

( F000 IS UNBOUND ATOM) 

UNTRACE: 

XEEEE FOOO 
E 
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Undefined function calls from complied code 

Frequently, a function will be compiled when some of the functions 
it calls are not defined. The compiler merely generates instruct- 
ions for calling the function exactly as though it were defined 
as a LAMBDA expression (p. 16. 7). However, if the function is 
undefined at run time, the system routine that performs the actual 
calling of functions will instead call the function interrupt , 
analagous to faulteval in the interpreter. Interrupt is defined 
to type UNDEFINED FUNCTION followed by the function name and then 
call breakl. 

If the function was undefined at compile time, its arguments will 
have been evaluated (see p. 16.7). In this case, they may be 
examined using the function arg , p. 8.6. e.g. arg(l), arg(2), or 
the function breaknargs can be used to make a list consisting of 
all of the arguments to the function. For example, the expression 
given to breakl as brkexp is (APPLY FUNCTION (BREAKNARGS 
INTERRUPTARGS)) where interrupt args is the argument to interrupt , 
and is bound to the number of arguments for the undefined function, 
i.e. the number of arguments with which is was called, and the 
variable function is bound by interrupt to the undefined function 
name. If the user defines function as a LAMBDA expression, and 
executes the OK, GO, or EVAL command in breakl , the correct value 
will be computed. 

As with faulteval , the value returned by interrupt is used as the 
value for the function call, and the computation proceeds exactly 
as though no error had occurred. 
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Similarly, the call to breakl can be inhibited by setting the 
variable helpflag to NIL, and no break occurs if the error was 
within helpdepth function calls from the top or the last errorset. 
In these cases, error is called instead. 

Inducing an interrupt 

The user can induce an interrupt and subsequent call to breakl at 
any point in a computation by typing control-H. At the next 
point a function is about to be entered, interrupt is called in- 
stead. Interrupt types INTERRUPTED BEFORE followed by the function 
name, and then calls breakl exactly as though the function were 
undefined. The arguments to the function can be examined using 
arg or breaknargs . If the user types OK, GO, or EVAL the function 
call will be continued. Control-H interrupts are not affected by 
the setting of helpflag or helpdepth . However, they only occur 
when a function is about to be entered. If the program is com- 
puting in a function which after compilation, does not call any 
other functions, (pp. 16. 11-16. 14) computation will not be inter- 
rupted until that function is exited. 
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"Real" errors 

The conventional treatment of errors in a LISP system is to 
cause a trap to a routine which prints an error message and un- 
winds the pushdown list. While unwinding the pushdown list, the 
system prints the names and arguments of all functions that have 
been entered but not yet exited, with the most recently entered 
function printed first. (*) If the function errorset has been 
entered, unwinding proceeds only as far as the most recent call to it, 
and errorset then returns NIL as its value, to indicate an error 
occurred. Otherwise, unwinding proceeds until the top level eval- 
quote. 

In the BBN LISP system, this unwinding process takes place only 
as a last resort, i.e. if the variable helpflag is NIL, or if the 
error type (p. 15.29) is specified as non-helpable, or if the error 
occurred within helpdepth function calls from the top or the last 
errorset . Otherwise, the error diagnostic is printed and breakl 
is called to allow the user to examine the state of the computation 
and proscribe the next action. 

Unfortunately, the user may not always be able to make a correction 
and proceed as if no error had occurred, as he can with calls to 
faulteval and interrupt . When an error occurs in a low-level 
routine, the state of the computation must be backed up to the 
last function call before breakl can be called. For example, if 
the compiled function hypotenuse were defined as: 



(*) In the BBN system, this printout can be terminated by pressing 
control-R, or portions of it can be skipped by judicious use 
of rubout, or the printlevel can be modified by using control-P, 
or the user can always bomb back to the top level via control-C. 



See appendix 2, p. 23.7. 
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C HYPOTENUSE 

(LAMBDA (X Y> 

(EXPT (FPLUS (FTIMES X X) 
CFTIMES Y Y>) 
0.50000000))) 



and the user performed: 



-E (FTIMES (SINE 30) (HYPOTENUSE 3)) 

NON-NUMERIC ARG 
N IL 

1 N HYPOTENUSE 

(HYPOTENUSE BROKEN) 

: BTv 

UNTRACE: 

Y NIL 

X 3 
HYPOTENUSE 

LAMBDA & 

%A 0*50000000 
FTIMES 

XEEEE & 
E 

: (SETQ Y 4) 

A 

: EVAL 

HYPOTENUSE EVALUATED 

: VALUE 

5 

: OK 

HYPOTENUSE 

2 • 50000000 
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the computation would be preserved as of the time hypotenuse was 
called, since ftimes and fplus compile open (p. 16.10). 
Thus the partial results of the computation would be lost when the 
error occurred. In this particular case, the user could proceed 
as shown. 

However, if the computation made some changes in the program's 
environment before the error occurred, the programmer may not be 
able to simply repeat the computation. For example, if hypotenuse 
were defined as: 

- PRETTYPR I MTC (HYPOTENUSE)) 

( HYPOTENUSE 

(LAMBDA (X Y) 

(EXPT (FPLUS (SETQ X (FTIMES X X)) 
(FTIMES Y Y)) 
0.50000000))) 
N IL 

•■E (FTIMES (SINE 30) (HYPOTENUSE 3)) 

NON-NUMERIC ARG 

N IL 

I N HYPOTENUSE 

(HYPOTENUSE BROKEN) 

: X 

9 

: RETURN (HYPOTENUSE 3 4) 

HYPOTENUSE = 5 

2 .50000000 

4» 

The user must evaluate each situation individually to decide 
whether or not he can continue, or should force a returned value, 
or perform a ret from back to some higher level. 
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Error types 

There are currently twenty four error types in the BBN LISP system 






NONXMEM 


1 


BREAK 


2 


CAR OP NUMBER 


3 


PDL OVERFLOW 


4 


UNDEFINED FUNCTION 


5 


FUNCTION 'ARG' NOT LEGAL 


6 


ATOM STORAGE FULL 


7 


PNAME STORAGE FULL 


8 


UNREASONABLE LINE LINE LENGTH 


9 


ILLEGAL RADIX SETTING 


10 


ILLEGAL INPUT FORMAT 


11 


ILLEGAL REGISTER COMMAND 


12 


ILLEGAL FILE NAME 


13 


NOT USED (UNLUCKY) 


14 


NON-NUMERIC ARG 


15 


NON-ATOMIC ARG 


16 


ATTEMPT TO CLOBBER NIL 


17 


NUMBER STORAGE EXCEEDED 


18 


ERROR 


19 


ILLEGAL GO 


20 


ILLEGAL RETURN 


21 


QUIT 


22 


INCOMPATIBLE 


23 


NOT FOUND 


24 


TOO MANY CHARACTERS IN ATOM 
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Explanation of error types 
NONXMEM 



BREAK 

CAR OP NUMBER 

PDL OVERFLOW 

UNDEFINED FUNCTION 



FUNCTION »ARG f NOT LEGAL 



ATOM STORAGE FULL 



PNAME STORAGE FULL 

UNREASONABLE LINE SETTING 
ILLEGAL RADIX SETTING 
ILLEGAL INPUT FORMAT 

ILLEGAL REGISTER COMMAND 



reference to non -existent memory . 
Can occur if array-pointer or other 
unboxed number is treated as list 
structure, i.e. program tries to 
take car of it, but more frequently 
an indication that system is sick. 

User types control-R 

occurs when interpreter tries to 
take car of number, e.g. (COND 387 
(T NIL)) 

occurs from infinite recursion, 
where infinite means more than 1500 
nested function calls. 

very rare - means calling routine 
is very confused - normally it 
calls interrupt on undefined function 
as described above 

arg used inside a function that was 
not a no-spread, evaluate type 
function 

too many atoms, (current system can 
hold 3100 new atoms,) if a reclaim 
does not collect any of the user f s 
atoms, he can continue by flushing 
part of the system, p. 22.8, and 
then performing an atomgc , p. 10. 3. 

can occur if you have many atoms 
with long names 

linelength[n], n > 999. 

radix[n], n > 255. 

read is confused, e.g. it saw an 
expression like (A .) 

openr or closer given an illegal 
address. 
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ILLEGAL PILE NAME 

NON-NUMERIC ARG 

ERROR 

ILLEGAL GO 

ILLEGAL RETURN 

QUIT 

INCOMPATIBLE 

NOT FOUND 

TOO MANY CHARACTERS IN ATOM 



attempt to read from, write on, or 
close a file that is not open 

from numeric functions like plus , 
times , etc. 

call to function error 

go to nonexistent label 

call to return from outside a prog 

call to quit 

from sysin, see p. 14.11 

from sysin see p. 14.11 

> 86 



The list of non-helpable errors, nherrors , is initially set to 
(0 1 18). The rationale behind this is that NONXMEM are usually 
system malfunctions; control-R means abort-(control-H should be used 
to reouest for interaction), and error type 18, a call to error should 

not be helpable: the function help , p. 15.33, is available for that 
purpose. However, the user_ can set nherrors to any list of error type 
numbers for which he does not wish the system to go into a break. 
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Error Messages 
errorn[] 



errorm[n;m] 



returns information about the last 
error in the form (n m) where n is 
the error type number and m is the 
argument to errorm which would 
normally be printed out after the 
error message. Thus if an unbound 
atom F00 had been encountered, 
errorn[] would yield (18 (POO IS 
UNBOUND ATOM)). In the example 
with hypotenuse on page 15. 28 errorn 
would yield (14 NIL). 

prints message corresponding to an 
errorn that yield (n m) . For 
example, errorm[l8, (F00 IS UNBOUND 
ATOM)] would print ERROR 

(F00 IS UNBOUND ATOM) 
errorm[l4;NIL] would print 
NON-NUMERIC ARG 
NIL 

and errorm[2*J] would print out just 
TOO MANY CHARACTERS IN ATOM 
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Error Functions 



error[x] 



he lp [he lp x ; he lpy ] 



errorset[ersetx;ersetflg] 



causes an error, type 18, with 
message X. 

Generates an error with message 
helpx, that is helpable i.e. 
breakl will be called, if either 
helpf lag or he lpy is T, regardless 
of the depth, help is a convenient 
way to program a default condition, 
or to terminate some portion of a 
program which theoretically the 
computation is never expected to 
reach. 

performs eval[ersetx] . Note that 
errorset is a lambda-type of function, 
and that its arguments are evaluated 
before it is entered, i.e. errorset[x] 
means eval is called with the value 
of x. If no error occurs in the 
evaluation, the value of errorset 
is a list containing one element, 
the value of eval[x]. If an error 
did occur, the value of errorset is 
NIL. Note that NIL can be returned 
only if there was an error. If the 
value eval[x] is NIL, the value of 
errorset is (NIL). 

The argument ersetf lg controls the 
printing of error messages. If 
ersetflg=T, the error message is 
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printed; if ersetflg= NIL it is not. 
If ersetflg = IGNORE, the errorset 
is ignored. Thus you can make an 
errorset "go away" while still in- 
side of it. 

Note: errorset is defined as just 
(LIST (EVAL ERSETX)). All of the 
errorset-ing effect is performed 
in errorx , described below, after 
an error occurs. 

ersetq[ersetx] nlambda performs errorset[ersetx;t], 

i.e. (ERSETQ (POO)) is equivalent to 
(ERRORSET (QUOTE (POO)) T) 

nlsetq[nlsetx] nlambda , performs errorset[nlsetx;NIL] 

esgag[x] sets esgag to x, returns old value. 

If esgag is T, an untrace will be 
printed during unwinding to an error- 
set. If it is NIL, no untrace will 
be printed. Initially set to NIL. 

quit[x] Induces a "strong" error which will 

unwind through errorsets to the top 
level. It prints the error message 
x and an untrace. 

reset [] Induces a "strong" error which will 

immediately return you to the top 
level with no untrace. reset is 
esentially a programmable control-C. 
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Errorx 

For completeness, and a summary of the error handling facilities, 
this section describes how errorx , the basic error handling routine 
of the system is written using nthfn , nthfnback , errorm , errorn , 
backtrace , reset , evalv , and ret from . 

Errorx is called for all 23 error types. It first performs an 
errorn to determine the error number. If this number is not a 
member of the list nherrors and he lp f lag is T, and the difference 
between nthfn[ERRORSET;l] the position of the last call to errorset , 
(0 is used if nthfn returns NIL i.e. no calls to errorset ) and 
nthfn [ERRORX; 1] is not greater than helpdepth , errorx calls errorm 
to print the error message, and then calls breakl . 

If there were no calls to errorset , or the value of ersetflg was 
IGNORE for all of the calls to errorset , errorx calls errorm to 
print the message, calls backtrace to print the untrace, and calls 
reset to get back to the top level. 

Otherwise, errorx looks at the value of ersetflg with evalv to 
determine whether to print a message. If this value is T, 
errorx prints the error message using errorm . If esgag is T, errorx 
calls backtrace to print the untrace. Finally, errorx does a 
retfrom[nthfn[errorset;l]NIL] to return NIL from the last errorset. 
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SECTION XVI 

THE COMPILER AND ASSEMBLER 

The Compiler 

The compiler is available in the regular LISP system. It may be 
used to compile individual functions as requested or all function 
definitions in a standard format LOAD file. The resulting code 
may be loaded as it is compiled, so as to be available for immediate 
use, or it may be written onto a file for subsequent loading. 
The compiler also provides a means of specifying sequences of 
machine instructions for special purposes. 

The most common way to use the compiler is to compile from a 
symbolic file, producing a corresponding file which contains a 
logical set of functions in compiled form which can be quickly 
loaded. An alternate way of using the compiler is to compile 
from functions already defined in the user's LISP system. In 
this case, the user has the option of specifying whether the 
code is to be saved on a file for subsequent loading, or 
the functions redefined, or both. In either case, the compiler 
will ask the user certain questions concerning the compilation. 
The first question is 

(LISTING?) 

The answer to this question controls the generation of a listing 
and is explained in full below. However, for most applications, 
the user will want to answer this question with either ST or F, 
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which will also specify an answer to the rest of the questions 
which would otherwise be asked. ST means the user wants the com- 
piler to Store the new definitions; F means the user is only- 
interested in compiling to a Pile, and no storing of definitions, is 
performed. In both cases, the compiler will then ask the user 
one more question: 

(OUTPUT FILE?) 

to which the user can answer 

NIL no output file. 

file-name file is opened if not already opened, and compiled code 
is written on the file.* 

Example: 

COMPILE ((PACT PACT1 PACT2)) 

(LISTING?) 

ST 

(OUTPUT PILE?) 

/CPACT/ 

(PACT COMPILING) 

• 

(PACT* REDEFINED) 



(PACT2 REDEFINED) 
(FACT FACT1 FACT2 ) 

This process caused the functions FACT, FACT1, and FACT2 to be 
compiled, redefined, and the compiled definitions also written on 
file /CPACT/ for subsequent loading. 



Note some compiler functions will leave the output file open, 
others do not. Consult the description of each particular 
function. 
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Compiler Functions 

complle[x] This will compile all the functions 

on the list x. Returns a list of 
the functions compiled. Leaves 
output file open. 

Note: Certain compiler functions leave the output file, if any, 

open so the user can perform several compilations to the same 

file. When finished, compiled files should be closed by per- 
forming endf lie [file-name]. 

recompile [pretty file ; compiledf lie ; fns] 

The purpose of recompile is to allow 
the user to update a compiled file 
without necessitating a complete re- 
compilation, recompile does this by 
using the results of a previous com- 
pilation, and is considerably faster 
than compiling an entire file from 
scratch. 

compiledfile is a disc file contain- 
ing functions in compiled form. 
prettyfile is a disc file made by 
prettydef . recompile makes a new file 
that is equivalent to performing: a 
tcompK (prettyfile)). (If the out- 
put file from tcompl would have the 
same name as compiledfile , the us*er is 
asked to name the output file.) Every 
function defined in prettyfile that 
appears on the list fns is compiled 
from its definition in prettyfile . For 
all other functions in prettyfile , 
recompile reads from compiledfile 
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until it finds the compiled version 
and then simply copies it onto the 
output file. Note that the user can 
thus modify an old compiled file so 
as to add new functions by pretty- 
defing them and then including them 
on the list fns. Similarly, he 
can delete functions by not putting 
them in pretty file . Warning : this 
procedure assumes that the order of the 
functions in complledfile follows that 
of prettyfile . 

Note: when a function is compiled from an in core definition, 
i.e., via compile as opposed to recompile or tcompl , 
which use definitions from a file, and it has ^been modified by 
break , b re akin or advised , the function is restored to its 
original state before compilation. If the user wishes to compile 
a function with its advice, he should use the function cadvice 
described on page 19.10. 



rcompile[] 



tcompl[x] 



Compiles from a file whose name 
will be requested after the compset 
questions have been answered. This 
should be a disc file because it will 
be open during the entire compilation. 
The value of this function is NIL. 
Closes output file. 

x is a list of file names. Performs 
a rcompile for each of the files in 
the list. The user is not asked to 
specify an output file for each file. 
Instead, the output from the compila- 
tion of each file will be written on 
a file of the same name prefixed with 
a c_. The value of tcompl is a list 
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of the names of the output files. 
All output files will be properly 
terminated and closed. Note: due to 
present restrictions of the 9^0 file 
system, only disc files (names begin- 
ning with a slash) should be used. 
Example: 

TCOMPL ((/SYM1/ /SYM2/ /SYM3/)) 
creates files 
/CSYM1/, /CSYM2/, /CSYM3/ 

compile2[name;def ] Compiles def , redefines name if 

strf= T, (described below). This 
is the function to call if you wish 
to use the compiler as a subroutine, 
i.e., from another function as op- 
posed to direct input from teletype; 
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Compiler Questions 

The compiler uses the free (top level) variables LAPFLG, STRF, SVFLG, 
NLAMA, NLAML, LCPIL and LSTFIL which determine various modes of 
operation. These variables are set by the answers to the "compset" 

questions. When any of the top level compiling functions have 
been called, the function compset is called which asks a number 
of questions. Those that can be answered "yes" or "no" can be 
answered with YES, Y or T for YES; and NO, N, or NIL for NO. 
The questions are: 

(LISTING?) 

The answer to this question controls the generation of a listing. 
Possible answers are: 

1 Prints output of pass 1, the LAP macro code. 

2 Prints output of pass 2, the LAP2 machine code. 
YES Prints output of both passes. 

NO Prints no listings. 

The variable LAPPLG is set to your answer. 

The LAP and LAP2 code is usually not of interest to the user. 
There are three other possible answers to this question, each of 
which specifies a complete mode for compiling. They are: 

S Same as last setting 

P Compile to Pile (no definition of function) 

ST Store new definitions 

Implicit in these three are the answers to the questions 

on disposition of compiled code, expr's and NLAMBDA's, so these 

questions will be skipped. These questions are discussed below. 
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(STORE AND REDEFINE?) 

YES Causes each function to be redefined as it is compiled. 
The compiled code is stored and the function definition 
changed. The variable STRP is set to T. 

NO Causes function definitions to remain unchanged. 
The variable STRP is set to NIL. 

The answer ST for the first question implies YES for this question, 
P implies NO, and S makes no change. 

(SAVE EXPRS?) 

If you answer this YES, SVPLG will be set to T, and the exprs 
will be saved on the property list of the function name. Other- 
wise they will be discarded. The answer ST for the first question 
implies YES for this question, P implies NO, and S makes no change. 

When compiling the call to a function, the compiler must prepare 
the arguments in one of three ways : 

1. Evaluated (SUBR, SUBR*, EXPR, EXPR*, CEXPR, CEXPP*) 

2. Unevaluated, spread (FSUBR, PEXPR, CPEXPR) 

3. Unevaluated, not spread (FSUBR*, FEXPR*, CFEXPR*) 

In attempting to determine which of these three is appropriate, 
the compiler will examine the definition of the called function 
if there is one, otherwise it will check all the functions in 
the file being compiled, and failing this, will assume type 1 
above . Therefore, if there are type 2 or 3 functions called 
from the functions being compiled, and they are only defined in 
a separate file, the following two questions must be answered. 
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(NO-SPREAD NLAMBDAS-) 

The answer to this question sets the variable NLAMA. If there 
are any NLAMBDA's with atomic argument lists called from your 
functions to be compiled, and they are not defined, answer the 
question with one of the following: 

S Means Same list as now on the 

free variable NLAMA 



ADD (fn^ . . . ;fn k ) 



Add fru to fn, to list saved on 

NLAMA 



REMOVE (fn^. . .;fn k ) 



Remove functions from NLAMA 



EDIT 



The editor will be called and 

you can edit the list of functions 



(fn x ;.. .fn k ) 



Set NLAMA to the list of functions 



NIL, N, NO 



Set NLAMA to NIL 



Any other atom will cause a question mark to be printed and let 
you answer again. Then compset will ask: 

(SPREAD NLAMBDAS-) 

Answer in the, same way. The free variable used by the compiler 
is NLAML this time. The answers ST, P, or S to the first question 
leave the settings of NLAMA and NLAML unchanged. 
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(OUTPUT PILE) 

This question is always asked except under TCOMPL. You should 
usually provide the name of a disc file on which you wish 
to save the code generated. If you answer T, TTY or TELETYPE, 
the listing will be typed out on the teletype. If you answer N, 
NOTHING or NIL, output will not be done. If the file named is 
already open, it will continue to be used. The free variable 
LCFIL is set to the name of the file. 

When the compiler is operating, it will normally print on the 
teletype the name of the function compiling, a list of its bound 
variables and a list of its free variables. 

When you have finished compiling all the functions you wish to 
dump on one disc file, close the file endfile. 



The code dumped on the file can be loaded into any standard 
system with load. 
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Compiler Structure 

The compiler has two principal passes. The first compiles its 
input into a prefix macro assembly language called LAP. The 
second pass expands (and optimizes) the LAP code and produces a 
simple assembly language (one instruction per line) called LAP2. 
This output is either dumped onto a file and/or loaded into array 
(binary program) space and the function redefined. 

The input for the compiler can be either a standard LISP function 
definition (the normal usage), or an assemble form, which allows 
direct machine language coding within LISP in a convenient form. 

The compiled code generated always links between functions by 
using a special call-enter pair of routines. This is necessary 
because a function may not be in core when called, and this is 
checked in a binary function hash table. A function must be 
brought into the in-core binary program buffer to run. 



The linkage routines also set up the parameter and control push 
lists as necessary for variable bindings and return information. 
In some cases discussed below, the linkage routine can be avoided 
(saving about a millisecond a call) by compiling short functions 
"open." Some often used functions, such as car and cdr» are 
always called open by the compiler (a complete list is given later) 
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Open Functions 

It is useful to know what LISP forms do not result in function 
calls after they are compiled since function calls take a signifi- 
cant time. Thus, it is more economical to perform 

(AND (NULL (EQ (CAR X) 4)) (OR Y (NULL (ATOM Z)))) 



in a compiled function than to call another function. In addition 
to functions such as addl, subl, memb , etc. which compile open 
via macros, the compiler specifically checks for certain functions 
like plus , times , car , cdr , etc. and handles them in an efficient 
way. Below is a list of those functions which when compiled do 
not result in external function calls. Note: that mapc and map 
will require a call if their functional argument requires one. 



ABS 
ADD1 
AND 

ARRAYP 
ASSEMBLE 
ATOM 
CAR 
CAAR 
CAAAR 
etc. 
CDDDAR 
CDDDDR 
COND 

DIFFERENCE 
DIVIDE 
EQ 
FIXP 
FLOATP 
FMINUS 
FPLUS 
FQUOTIENT 
FTIMES 
GO 

GREATgRP 
LESSP 
LISTP 
LOC 

LOGAND 
LOGOR 
LOGXOR 



LRSH 

LSH 

MAP 

MAPC 

MEMB 

MINUS 

MINUSP 

NEQ 

NLISTP 

NOT 

NULL 

NUMBERP 

OR 

PLUS 

PROG 

PR0G1 

PR0G2 

PROGN 

QUOTE 

QUOTIENT 

REMAINDER 

RETURN 

RSH 

SELECTQ 

SETQ 

SUB1 

TIMES 

VAG 

ZEROP 



16.11 



Affecting the Compiled Code 

There are three ways to affect code compiled for you. You 
can make a function fn compile open (as an open LAMBDA or NLAMBDA 
expression) by putting the expression defining it (including the 
LAMBDA or NLAMBDA) on the property list of fn after the flag MACRO, 
and adding fn to the list which is the value of OPENFNS. Abs and 
memb are functions currently compiled open. The effect is the same 
as if you had written this expression in place of fn wherever it 
appears in a function being compiled. This saves the time necessary 
to call a function (about a millisecond) at the price of more 
compiled code generated. 

By putting on the property list of fn under the flag MACRO an 
expression starting with an atom other than LAMBDA, one can 
actually compute the LISP expression to be compiled in place of 
the call to fn. The atom which starts the list is bound to cdr 
of the form in which fn appears. The expression following the 
atom is evaluated,* and the result of this evaluation is compiled. 
List , mapc and map are compiled using this technique. For 
example: list has on its property list the expression 
(X (GLIST X)), where glist is defined as 

(LAMBDA(L) (COND( (NULL L)NIL) (T (LIST (QUOTE CONS) (CAR L) 
(GLIST (CDR L))))) 

this causes (LIST X Y Z) to be compiled as 

(CONS X (CONS Y (CONS Z NIL))). 

If the value of the result of this evaluation is the atom 
INSTRUCTIONS, no code will be generated. It is then assumed the 
evaluation was done for effect and the necessary code has been 



* The evaluation is done by the function expandcomp , which takes two 
arguments, the property value for MACRO, and cdr of the form in 
which fn appears, and returns the expression to be compiled. This 
is the function to break on if you want to see if your macro is ex- 
panding correctly. 
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added. This is a way of giving direct instructions to the compiler 
if you understand it. 

Finally, an expression following MACRO on the property list can 
start with a list of atoms, which are then used as variables for a 
substitution MACRO. Each atom is paired with a corresponding 
element in the form containing fn. Then these elements are 
substituted for their paired atoms in the expression following 

the list of atoms, and this substituted expression is compiled. 
The functions 

addl, subl , neq , zerop , lessp , minusp , difference , ersetq 
and nlsetq 

are all compiled open using these substitution macros. For 
example, on the property list of addl is the expression 
((X)(PLUS XI)). Thus, (ADD1 (CAR X)) is compiled as 
(PLUS (CAR X) 1). Note that a function like times2 defined as 
(LAMBDA (X) (PLUS X X)) could be compiled open or could be made 
a substitution macro. The macro, however, would cause 
(TIMES2 (F00 X)) to compile as (PLUS (F00 X) (F00 X)) and conse- 
quently (F00 X) would be evaluated twice. In this case it is 
better to use an open macro - i.e., put (LAMBDA (X) (PLUS X X)) 
on the property list of TIMES2, so that its argument would only 
be evaluated once. 
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Note: 

Expressions that begin with FUNCTION will always be compiled 
as separate functions named by attaching a gensym to the end 
of the name of the function in which they appear, e.g. FOOA0003. 
This latter function will be called at run time. Thus if F00 
is defined as (LAMBDA (X) ... (F001 X (FUNCTION ...)) ...) and 
compiled, then when F00 is run, F001 will be called with two 
arguments, X, and FOOAOOOn, and then FOOl will call FOOAOOOn 
each time it must use its functional argument. A considerable 
savings in time can be achieved by defining FOOl as a macro of 
type two: 

(MACRO X (LIST (SUBST (CADADR X) (QUOTE FN) *) 
(CAR X))) 
where * is the definition of FOOl as a function of just its first 
argument and FN is the name used for its functional argument. 
This expression will be evaluated at compile time and produce an 
expression to be compiled that contains the actual definition of 
the function that would have been the second argument to FOOl had 
FOOl not been compiled open. Thus you save the function call to 
FOOl and each of the function calls to its functional argument . 
For example, if FOOl operates on a list of length ten, eleven 
function calls will be saved. Of course, this savings in time 
costs space, and the user must decide which is more important. 

Free Variables and EVQ 



As discussed in section 12, free variables used by a function are 
detected at compiled time so that when the compiled function is 
entered, its free variables can be bound locally. This procedure 
saves searching the entire push-down list each time a free variable 
is used in the compiled function. However, if the user knows that 
the particular portion of the function that references the free 
variable will only be reached infrequently, he may opt to search 
the push-down list only when the value of the free variable is 
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needed. This can be done by using the form (EVQ variable) instead 
of variable. (For interpreted purposes, EVQ is defined as 
(LAMBDA (X) X).) Note that if a free variable will be used more 
than once in a function, it is more efficient to search for its 
binding once , when the function is entered, than each time the 
variable is used. 

Changing the Binary Program Buffer 

While running binary code, a program ring buffer of 4K is used to 
contain active program. The size of this buffer can be affected 
by the following functions: 

contractl[] Contracts the in-core binary 

program buffer by one LISP 
(256 word) page, thereby also 
adding one virtual page buffer. 
Returns value of new higher 
boundary. Will not contract 
beyond a predetermined minimum 
amount, an assembly parameter 
(2K in 4-1-68 LISP). 

expandl[] Expands the in-core binary pro- 

gram buffer by one LISP 
(256 word) page, thereby also 
removing one virtual page buffer. 
Returns value of new lower boun- 
dary. Will not expand beyond 
predetermined maximum amount. 
(8K in 4-1-68. LISP) 

Note: Expanding the BP buffer will usually not be very effective 
in speeding up programs unless the code used is just larger than 
the current buffer size. Then expanding the buffer will allow an 
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all In core operation, rather than continuous shuffling of code 
back and forth from the drum. Contracting the buffer Is advanta- 
geous only when a relatively small compiled program is to be used 
for a considerable period, with a data base that requires more 
than 20 buffers. 

Assemble 

Using the LISP compiler, it is possible to define functions 
partially or completely in machine language. Machine language is 
specified by the pseudo-function assemble . assemble is, in fact, 
a compiler directive, and has no independent definition. Thus, 
it is not possible to interpretively run functions defined using 
assemble . 

The format of ASSEMBLE is similar to that of PROG. 

(ASSEMBLE V S ;L S 2 . . . S ) 

Each of the statements S are interpreted sequentially during 
compilation according to the rules given below. V is a list of 
variables to be bound during compilation, not, it must 
be noted, during the running of the object code. Interpretation 
of each S will usually result in the generation of one or more 
instructions of object code. Some S, however, may result in no 
object code being generated. Note than an ASSEMBLE statement 
can appear anywhere in a LISP function, e.g., you can write 

(SETQ Z (PLUS X (LOC (ASSEMBLE NIL (BRS 42))) Y)) 

The value of the pseudo- function assemble is determined by what 
is left in the A register after the execution of the sequence 
of assemble instructions. 
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Assemble Statements 

If S is an atom, it is taken as a label identifying the next cell 
to be assembled. Otherwise, it is one of the following types of 
statements . 

(CQ CI C2 ...) 
CI, C2, ... are literal S expressions which are compiled in order 
in the usual way. 

(C El E2 ...) 
Same as CQ except the En are first evaluated and then compiled. 

The above two statements provide the ability to mix regular com- 
pilation with assembly. The value of the A register may be ob- 
tained within a compile statement by use of the function AC. It 
must, however, appear as the first argument to be evaluated in 
the expression. 

Example : 

(CQ (PLUS F00 1)) 

(C (CONS (QUOTE FNl) (CDR F00))) 

(CQ (PLUS (LOC (AC)) FIE -1)) 

(E El E2 .. .) 

The expressions El, E2, ... are evaluated in order for effect, 
i.e., no code is produced. 

Example: 

(E (SETQ SP (PLUS SP -3))) 
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(RETURN) 

Assembles an instruction which causes a return from the function 
being compiled (not from the ASSEMBLE expression), with the con- 
tents of the A register as the value. A return from the ASSEMBLE 
expression is done by "falling through" or branching to the instruc- 
tion following the last statement. The value is the contents of the 
A register at that time. 

(CALL NAME N) 

Assembles a call to the function NAME giving N arguments. The N 

arguments should be in stack positions 

SP-N+1, SP-N+2, ..., SP-1, SP. See Section "Compiler Conventions." 

Note: A, B, X registers are destroyed. 
(SETQ VAR) 

Assembles an instruction which stores the A register in the vari- 
able VAR. 

Note: The contents of the X register are an index to the parameter 
stack and are used by compiled code whenever a variable or temp 
storage cell is referenced. If the code specified by an assemble 
directive changes the X register, it should ( must) be restored 
with (LDX PPPTR) before executing any regular compiled code. 
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Lap Macros 

If CAR of the statement is an atom which has a LAP property-list 
macro definition, e.g., LDV, STV, etc., the arguments are evaluated 
and the results assembled. If CAR of the statement is a defined 
function, the function is called, without evaluating the arguments, 
and the result is treated as code. This feature would normally 
not be of use to the programmer; it is used by LAP in interpreting 
first pass code generated by the compiler. 

Assemble Macros 

If CAR of the statement has a property list value following the 
flag AMAC, it is assumed to be an assembler macro call. There 
are two types of assembler macros, substitution and lambda . A 
substitution macro is defined by an S expression, CAR of which is 
a list of dummy symbols. The arguments of the call will be sub- 
stituted for corresponding appearances of the dummy symbols in CDR 
of the defining form and the resulting list of statements will be 
assembled. 

If CAR of the defining form is the atom LAMBDA, the entire 
defining form will be applied to the arguments of the call. 
Note that either of these may be indefinitely recursive. 
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Example: 

DEPLIST (( 



(UBOX ((VAR LOC) 

(CQ (VAG VAR)) 
(STA LOC))) 

(UBOXN (LAMBDA XX 

(PROG (YY) 



LP (COND 

((NULL XX) 

(RETURN (CAR YY))) 
(T (SETQ YY (TCONC (LIST (QUOTE UBOX) 
(CAR XX) 
(CADR XX)) 
YY)) 
(SETQ XX (CDDR XX)) 
(GO LP))) 



)AMAC) 



The above defines two macros, one of each type. The first takes 
two arguments and expands into instructions which place the 
unboxed value of a numeric variable in a local cell. The second 
does the same thing for an indefinite number of pairs of arguments 
For each pair, it constructs a call to the first macro. 
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the call: 

(UBOX SUM XSUM) 

expands into: 

((CQ (VAG SUM)) 
(STA XSUM)) 

the call (UBOXN SI LI S2 L2 ...) 

first expands into 

( (UBOX SI LI) 
(UBOX S2 L2) 



) 
Machine Instructions 

If CAR of the statement is an atom defined as a machine instruction, 
e -g«3 b y having a property OPD with numeric value (see compiler 
conventions), 

(LDA Al A2) 

the remainder of the statement may contain J?, 1 or 2 expressions. 

If either Al or A2 or both are not present, is assumed as their 
value. 

A2 may be used to specify indexing and indirect addressing when 
required. I specifies indexing (equivalent to a value of 
20000000g), and J specifies indirect addressing (equivalent to 
a value of M0000g). Otherwise, A2 may be any expression which 
evaluates to a number and will be added iijto the assembled word. 
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If Al is a number, it is added unchanged into the assembled word. 

If Al is non-atomic, it is evaluated and the result added into the 
assembled word which is assumed to refer to a stack position , and 
handled accordingly. 

If Al is atomic, it is one of the following: 

= Specifies that A2 is a literal. 

The instruction will be assembled 
to address a cell which contains 
A2, e.g., (LDA = NIL). If A2 is a 
number, it will be unboxed. Works 
only for S expressions, does not 
work for local program symbols 
(tags). 

* Has the value of the current 

location, e.g., (BRU * 1) is a 
jump to next location. 

A member of V, the list of variables given to ASSEMBLE, or 
the variable SP or CODE: is evaluated and assembled as 

a stack position (as for Al 

non-atomic) . 

One of the system defined atoms such as SYSNIL, SPCELL, etc. 

the top-level value of the atom 
is added into the assembled word. 
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Any other atom is assumed to refer to a tag in the program. 
Note: the detection of an undefined label does not occur until 
pass 2 of the compiler by which time all labels have been trans- 
lated into generated symbols. Thus, the error comment 
"UNDEFINED LABEL" will inform the user of the problem, but will 
not specify which label is missing. 

If CAR of a statement is a number, it is treated as if it were 
preceded by an opcode of value 0. 
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Examples : 



(LDA BUF I) 

(ADD = i*7) 

(SKG = 0) 

(BRU * 2) 

(BRU LOCI) 

(E (BOX SP)) 

(CAB) 

(LDA = NIL) non-numeric literal 

(PCONS) fast CONS 

(CQ (RETURN (TCONC (AC) TCL) ) ) return, use of A register 

in compile 

LOCI (STA (PSTEP)) stack reference 



label reference, indexing 
numeric literal 

relative address 

evaluate - compiles an ENBOX 



(LDA SP) 

(STA SPCELL 1) 

(STA SPCELL (PLUS J 10)) 



stack reference 

global symbol reference 

indirection and address arithmetic 



TMP1 (0) 
TMP2 (0) 
BUF (BSS 100) 



temp storage 



block definition 



When using locations within the function for temporaries, remember 
that the core copy of a compiled function may be overwritten any 
time another compiled function is called or a return effected. In 
this case, all internal changes will be lost. 
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Use 

ASSEMBLE should appear in a function defined with the usual 
defining forms. To relieve the user of the burden of unnecessary 
detail, as much of the function as possible should be compiled. 
For example, to obtain a variable, it is best to write 

(CQ VAR) 
to load the value of a variable into the A register. 
Thus the function 

(LAMBDA (X) X) 

could be written 

(LAMBDA (X) (ASSEMBLE NIL 
(CQ X))) 

and would compile identically. 
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Compiler Conventions 

The user of assemble should understand the following basic 
things about how compiled code is run. As explained in 
Section XII, all variable bindings and temporary storage of 
values are kept on the parameter pushdown list. When a compiled 
function is entered, the parameter pushdown list contains, in 
ascending order of addresses: 

1. Pairs of words containing the names and values 
of arguments passed to the function. 

2. Blocks of four words containing the value, name, 
and old locations of free variables used in the 
function and a flag so indicating. 

3. Room for temporary storage, for arguments to lower 
level functions, and for PROG and LAMBDA bindings 
appearing in the body of the function. 

value of VI 

VI 
value of V2 

V2 



increasing 
addresses 



value of VN 
VN 
value of freely 
freel 
old pos. of freel 
-2 



PPPTR 
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The index register (and a cell called PPPTR) contain a pointer 
to the first cell of the temporary block (just after the free 
variable bindings). This portion of the stack is guaranteed to be in 
core, and the compiler keeps a variable MSP which contains the 
maximum stack position used. SP is the variable which usually 
contains the last stack position used. The function pstep adds 
one to SP, updates MSP if necessary and returns the incremented 
SP. Each increment by 1 of SP changes the PDL position by two 
cells. If any functions are called, care must be taken that the 
garbage collector and free variable searcher are not confused by 
random things on the push list. Use of the LAP macros STT (for 
store temporary) and STN (for store number unboxed) will avoid 
such problems. STT compiles into code which stores the value in 
the value word and in the name word of the stack position, thus 
erasing any old name left from earlier calls. This also indicates to 
the G.C. that the value word of the pair contains a pointer to 
be traced. STN stores an unboxed integer in the value word and 
a -1 in the name word as a flag to the G.C. not to mark from this 
value word. 



There are a number of values which are stored on atoms which may 
vary for different system assemblies. These are dumped in sym- 
bolic form on LAP files to make these files compatible across 
assemblies. 
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The following are programmed operator Instructions used by 
compiled code: 



CARCLL 

CDRCLL 

CONSCLL 

UNBOX 

ENBOX 

XCLL 

RETURN 

IPV 

ENTER 



car of A register 

cdr " " " " 

cons of A and B registers 

unbox number in A register (VAG) 

enbox quantity in A register (LOC) 

function call 

function return 

initialize prog variables 

enter function and setup args. 



The following top-level bindings are the location of cells con- 
taining quantities of interest or used for communication. 



SYSNIL 

SYST 

SYSTAT 

SYSNUM 

SYSINT 

TOPBPS 

FREELW 

CTEMP 

INTZRO 
SPCELL 

PPPTR 



contains NIL 

contains T 

contains lower boundary of atoms 

contains lower boundary of numbers 

contains lower boundary of integers 

contains upper boundary of array 
space in use 

contains lower boundary of list 
space in use 

communication with garbage 
collector 

intzro+n for -30 <_ n <_ 30 contains n 

first of a block of 100 cells for 
general use 

index to push list in core 
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The following is a list of all machine operation, and programmed 
operator codes defined in the computer system. 



ADC 


5700000 


ADD 


5500000 


ADM 


6300000 


BAC 


4600012 


BIO 


57600000 


BRM 


4300000 


BRR 


5100000 


BRS 


57300000 


BRU 


100000 


BRX 


4100000 


BSS1 





BXC 


4600022 


CAB 


4600004 


CAX 


4600400 


CAXB 


4 6 00 4 4 


CBA 


4600010 


CBX 


4 6 00 2 


CIO 


56100000 


CLA 


4600001 


CLAB 


4 6 00003 


CLB 


4 6 0000 2 


CLX 


24600000 


CNA 


4 601000 


CTRL 


57200000 


CXA 


4 6 00 200 


DIV 


6500000 


EAX 


7700000 


FOR 


1700000 


ETR 


1400000 


EXU 


2300000 


FAD 


55600000 


FDV 


55300000 


FMP 


55400000 


FSB 


55500000 


GCI 


56500000 


LCY 


6720000 


IDA 


7600000 


LDB 


7500000 


LDE 


4600140 


LDF 


56600000 


LDX 


7 100000 


LRSH 


6624000 


LSH 


6700000 


WIN 


6100000 


MRG 


1600000 


MUL 


6400000 


NOD 


6710000 


NOP 


2000000 


NSTft 


3500000 



OVT 


2200101 


PFFV 


1 3400000 


PLAI 


1 1200000 


PMFN 


13500000 


PSAI 


1 1300000 


PSTR 


14100000 


RCY 


6620000 


ROV 


2200001 


RSH 


6600000 


SKA 


7200000 


SKB 


5200000 


SKD 


7400000 


SKE 


5000000 


SKG 


7300000 


SKM 


7000000 


SKN 


5300000 


SKR 


6000000 


STA 


3500000 


STB 


3600000 


STE 


4600122 


STF 


56700000 


STX 


3700000 


SUB 


5400000 


sue 


5600000 


SXMA 


6200000 


TCI 


57400000 


TCO 


57500000 


VAL 





WCH 


56400000 


WCI 


5570000k) 


WIO 


56000000 


XAB 


4600014 


XMA 


6200000 


XXB 


4600060 
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Appendix 

This section contains listings of those compiler and lap macros 
which are normally included with the compiler system. There 
are no assemble macros pre-defined. 

Compiler Macros 

(DEFLIST(QU0TE( 

(LIST (X (GLIST X) ) ) 
(ADD1 ((X) 

(PLUS X 1))) 
(SUB1 ((X) 

(PLUS X -1))) 
(NEQ ( (X Y) 

(NOT (EQ X Y) )) ) 
(NLISTP ((X) 

(NOT (LISTP X) ) )■) 
(ZEROP ((X) 

(EQ X 0))) 
(MINUSP ( (X) 

(GREATERP X) ) ) 
(DIFFERENCE ( (X Y) 

(PLUS X (MINUS Y) ) ) ) 
(ABS (LAMBDA (X) 
(COND 

( (GREATERP X) 

(MINUS X) ) 
(T X)))) 
(ERSETQ ((X) 

(ERRORSET (QUOTE X) 
T))) 
(EVQ (X (COND 

( (ATOM (CAR X) ) 

(STORECOMP (LIST (QUOTE LFV) 
(CAR X) ) ) ) 
(T (CEXPR (CAR X) ) )) 
(QUOTE INSTRUCTIONS) ) ) 
(MAP (X (LIST (SUBPAIR (QUOTE (MAPF MAPF2)) 
(LIST (CFNP (CADR X) ) 
(COND 

( (CDDR X) 

(CFNP (CADDR X) ) ) 
(T (QUOTE CDR)))) 
(QUOTE (LAMBDA (MACROX) 
(PROG NIL 
LP (COND 

( (NULL MACROX) 
(RETURN) ) ) 
(MAPF MACROX) 

(SETQ MACROX (MAPF2 MACROX)) 
(GO LP) 



)))) 
(CAR X)))) 
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(MAPC (X 



(LIST ( 

LIST (C 

(COND 

( (CDDR X) 

(C 

(T ( 

QUOTE ( 

(PRO 

LP 



SUBPAIR (QUOTE (MAPCF MAPCF2)) 
FNP (CADR X) ) 



(CA 
(MEMB (LA 
(PROG 
LP 



))) 

(NLSETQ ( 

(ERRO 

NIL 

(VAG (x ( 

(COND 

((E 

( 

(T 

(QUOT 

(LOC (x ( 

(COND 

((E 

( 
(T 
(QUOT 



FNP (CADDR X) ) ) 
QUOTE CDR) ) ) ) 
LAMBDA (MACROX) 
G NIL 
(COND 

( (NULL MACROX) 
(RETURN) ) ) 
(MAPCF (CAR MACROX)) 
(SETQ MACROX (MAPCF2 MACROX)) 
(GO LP) 
)))) 
R X)))) 

MBDA (MACROX MACROY) 
NIL 
(RETURN (COND 

( (NULL MACROY) 

NIL) 
( (EQ MACROX (CAR MACROY) ) 

(IFPRED T MACROY) ) 
(X (SETQ MACROY (CDR MACROY)) 
(GO LP)))) 

(X) 

RSET (QUOTE X) 

))) 

CEXPR (CAR X)) 

Q (CAADR CODE) 

(QUOTE ENBOX) ) 
RPLACA (CDR CODE) ) ) 
(STORECOMP (QUOTE (UNBOX))))) 
E INSTRUCTIONS) ) ) 
CEXPR (CAR X)) 

Q (CAADR CODE) 

(QUOTE UNBOX) ) 
RPLACA (CDR CODE) ) ) 
(BOX SP) ) ) 
E INSTRUCTIONS) ) ) 
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(FRPLAC (X (CEXPR (CAR X) ) 

(STS) 

(CEXPR (CADR X)) 

(STORECOMP (LIST (QUOTE MSAI) 
SP) ) 

(SETQ SP (SUB1 SP) ) 

(QUOTE INSTRUCTIONS))) 
(ASSEMBLE (ASEHX (ASEM1 ASEMX)) 

) 
(AC (X (QUOTE INSTRUCTIONS))) 
(IFPRED (AA (COND 

(EBRF (CAR AA) ) 
(T (CADR AA) ) ) ) ) 
(ARG (X (CEXPR (LIST (QUOTE VAG) 
(CAR X) )) 
(STORECOMP (LIST (QUOTE ARGN) 
(COND 

(ARGARG) 

(T (ERROR (QUOTE (FUNCTION 'ARG' NOT LEGAL))))))) 
(QUOTE INSTRUCTIONS) ) ) 
(SETARG (X (CEXPR (LIST (QUOTE VAG) 
(CAR X))) 
(STORECOMP (LIST (QUOTE STN) 

(PSTEP) ) ) 
(CEXPR (CADR X)) 
(STS) 

(LACOMP (SUB1 SP)) 
(STORECOMP (LIST (QUOTE SARGN) 
(COND 

(ARGARG) 

(T (ERROR (QUOTE (FUNCTION 'SETARG' NOT LEGAL))))) 
SP) ) 
(SETQ SP (PLUS SP w 2) ) 
(QUOTE INSTRUCTIONS))) 
(LSH (X (SHIFTCOMP (CAR X) 
(CADR X) 
(QUOTE LSH) ) )) 
(RSH (X (SHIFTCOMP (CAR X) 
(CADR X) 
(QUOTE RSH) ) )) 
(LRSH (X (SHIFTCOMP (CAR X) 
(CADR X) 
(QUOTE LRSH) ) ) ) 
) ) (QUOTE MACRO) ) 
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Lap Macros 



(CSP1 ( (LV LF LT) 

(LITREF LDA LV) 
(LITREF LDX LF) 
(LITREF LDB LT) 
(PRGREF PENT (PLUS 
:x ( (N P) 
LDV N) 



PLITORG 1)))) 



(SETI 
( 
( 
( 
( 
( 
( 
( 

(VST1 

( 

( 

( 

(BE ( 

( 
( 
( 
(BNE 

( 
( 
(LDV 

( 



N) 



PP) 
LDB LV) 
PIPV (PLUS 



SKE 
BRU 



N) 
2) 



N) 



(STV 
(LFV 
(LDT 
(STT 



( 

(NSTT 
( 



UNBOX) 
LSH 1) 
CNA 0) 
ARGSUB 
ADD PPPTR) 
STN P) ) ) 
( (PP LV V) 

LITREF LDA 
LITREF 
PRGREF 
(B N) 
STKREF 
RELREF 
JUMP B) ) ) 
((B N) 
STKREF SKE 
JUMP B) ) ) 
(LAMBDA (S) 
VREF (QUOTE 

S))) 
(LAMBDA (S) 
VREF (QUOTE 

S))) 
(LAMBDA 
LITREF 

S))) 
(LAMBDA 
STKREF 

S))) 
(LAMBDA 
STKREF 

S))) 

(LAMBDA (S) 
STKREF (QUOTE NSTA) 

S))) 



PLITORG V) )) ) 



LDA) 



STA) 



(S) 
(QUOTE 

(S) 
(QUOTE 

(S) 
(QUOTE 



PATV) 



LDA) 



STA) 
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(MSAI (LAMBDA (S) 

(STKREF (QUOTE PSAI) 
S))) 
(LQT (LAMBDA (X) 

(LITREF (QUOTE LDA) 
X))) 
(LDN (LAMBDA (S) 
(NREF (QUOTE 
S))) 
(STN (LAMBDA (N) 
(NREF (QUOTE 
N))) 
(CLL ( (L K U) 

(LITREF LDA 
(LITREF 
(LITREF 
(CLLA ( (L K 
(LITREF 
(LITREF 
(STKREF 
(ARGN ((A) 
(CLB 0) 
(LSH 1) 

(STKREF ADD A) 
(CAXB 0) 
(LDA I) 
(CBX 0))) 
(SARGN ( (A B) 
(CLB 0) 
(LSH 1) 

(STKREF ADD A) 
(CAB 0) 
(LDT B) 
(XXB 0) 
(STA I) 
(CBX 0))) 
(ARGSUB (LAMBDA (A) 



LDA) 



STA) 



V) 
LDB K) 
CLLX L))) 
U) 

LDA U) 
LDB K) 
CLLXA X))) 



(RET 
(BN 



(BNN 



(LITREF (QUOTE ADD) 

(PLUS -2 (VREF1 A) )■))) 

(NIL (PRETN 0) ) ) 
((B) 

(SKE SYSNIL) 
(RELREF BRU 2) 
(JUMP B))) 

((B) 
(SKE SYSNIL) 
(JUMP B))) 
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(BAP ((B) 

(SKG TOPBPS) 

(LITREF SKG 16383) 

(RELREF BRU 2) 

(JUMP B)) ) 
(BNAP ((B) 

(SKG TOPBPS) 

(LITREF SKG 163B3) 

(JUMP B) ) ) 
(BA ((B) 

(SKG SYSTAT) 

(RELREF BRU 2) 

(JUMP B) ) ) 
(BNA ((B) 

(SKG SYSTAT) 

(JUMP B) ) ) 
(BLST ((B) 

(SKG SYSTAT) 

(SKG TOPBPS) 

(RELREF BRU 2) 

(JUMP B)) ) 
(BNLST ((B) 

(SKG SYSTAT) 

(SKG TOPBPS) 

(JUMP B)) ) 

(UNBOX (NIL (PFVE 0) )) 
(ENBOX ((N) 

(PMKN N)) ) 
(FENBOX ((N) 

(PMFN N) ) ) 
(FUNBOX (NIL (PFFV 0) ) ) 
(NEG (NIL (CNA 0))) 
(DVD ((N X) 

(RSH 23) 

(DIV NX))) 
(DIVIDE ((S) 

(STTN S) 

(SWAP 0) 

(ENBOX S) 

(STKREF SXMA S) 

(ENBOX S) 

(STKREF XMA S) 

(CONSCLL S) ) ) 

(BI ((B) 

(SKG SYSNUM) 
(RELREF BRU 2) 
(JUMP B)) ) 
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(BNI 



(BIF 



(BUF 



(BII 



(BUI 



(BIS 



(BNS 



(BR1 



( 

(BH2 

( 

( 

(CONS 

( 

( 

( 

(CLLX 

( 

(CLLX 

( 

(SWAP 

(JUMP 

( 
(MPY 

( 
( 
(BSS 

( 
( 



((B) 
SKG SY 
JUMP B 
((B) 
SKG SY 
SKG SY 
RELREF 
JUMP B 
((B) 
SKG SY 
SKG SY 
JUMP B 
((B) 
SKG SY 
RELREF 
JUMP B 
((B) 
SKG SY 
JUMP B 
((B L) 
LITREF 
RELREF 
JUMP B 
((B L) 
LITREF 
JUMP B 
((B) 
PRGREF 
((B) 
RELREF 
PRGREF 
CLL (( 
CAB 0) 
STKREF 
PCONS 
((N) 
PCLL N 
A ( (N 
PCLL N 
(NIL 
((B) 
PRGREF 
( (N X) 
MUL N 
LSH 23 
(LAMBD 
SETQ L 
LIST ( 
N)) 



SNUM) 
))) 

SINT) 
SNUM) 

BRU 2) 
))) 

SINT) 
SNUM) 
))) 

SINT) 

BRU 2) 
))) 

SINT) 
))) 

1 SKE L) 

BRU 2) 
))) 

1 SKE L) 
))) 

BRU (GBS B) ) ) ) 

BRU 2) 

BRU (GBS B) ) ) ) 
N) 

LDA N) 
(TIMES N 2) ) ) ) 

))) 
X) 

X))) 
(XAB 0) ) ) 

BRU (GBS B) ) ) ) 

X) 

))) 

A (N) 

OC (PLUS LOC N -1 ) ) 

LIST (QUOTE BSS1) 

)) 
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SECTION XVII 

USING FORKS AND THE HYBRID PROCESSOR IN LISP 

The FORK logic provided by the 940 time-sharing system is avail- 
able for use by LISP programmers. Use of this very powerful fea- 
ture has made possible the efficient running of the hybrid pro- 
cessor for display output and speech input. Other operations are 
also available, such as running independent subsystems under con- 
trol of LISP. 

A fairly complete grasp of the machine-language environment pro- 
vided by the time-sharing system and the 940 hardware is necessary 
for a complete understanding of the basic operation of forks 
under LISP. However, a large class of jobs may be performed 
using the existing system functions which require only a minimal 
knowledge of fork operations. 

We will first discuss the storage organization of the LISP 
system and the conventions which have been established for the 
use of forks. The basic nature of forks will be discussed in 
sufficient detail to give anyone with a moderate knowledge of 
940 machine language a good understanding of their mechanics. 
Those not interested in programming at the machine language 
level should, nonetheless, be able to get a general picture 
of the nature of forks sufficient to understand the functions 
described below. 
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Forks 



In a time-sharing system such as that running on the 9^0, there 
may be several users running apparently simultaneously, each 
with his own "machine" (which may appear very much different 
from the actual machine), memory, files, etc. Obviously, the 
monitor program must have the ability to keep track of several 
programs at once. The 9^0 system makes it possible for the 
individual user to make use of this ability if he chooses. That 
is, he may cause the monitor to handle not one, but several 
"programs" for him at one time. These are called forks in the 
9^0 system. 

It is important to understand the concept of a fork. A fork 
is a complete process, capable of executing instructions and, in 
general, of performing all the operations of machine language 
programs. A fork is specified by several items: 

1. Central registers (PC, A, B, X) 

2. Memory (two relabeling registers) 

3. Status (running, waiting for I/O, etc.) 

The first two of these are needed to define a fork. That is, if 
the contents of the A, B and X registers are specified, and 
memory is provided (presumably containing instructions), a 
computation may be performed by simply telling the "computer" 
where to start (the function of the PC). The status is then 
determined by the nature of the instructions and how far the 
"computer" has gone. 
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On the 9^0, a fork may start one or more forks subordinate to 
itself. In fact, all programs are subordinate forks (at some 
level) of the EXECUTIVE program. The EXECUTIVE itself is a fork 
distinguished only by the fact that it has no higher level con- 
trolling fork. When one fork starts another, they are assumed 
to run concurrently, although in fact the machine can only be 
executing one instruction at any instant. 

A fork may have memory separate from or in common with its 
controlling fork, or both. It is this fact which gives forks 
their main usefulness to LISP. The 9^0 gives the user up to 
32K of private (accessable to no other user) memory divided into 
16 pages. Because the address part of a 9^0 instruction is 
14 bits, a program can directly address only 16K of this memory. 
A program may, however, change its map or create a fork by which 
the same addresses can be made to refer to different sections of 
the 32K private memory. (See BRS manual "Memory Allocation and 
Sharing" for a detailed discussion of this). 
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LISP Memory Allocation 

There are several different levels of storage used by LISP, and 
it is important to understand the distinctions. First, there is 
the large LISP virtual memory, so called because there is, in 
fact, no contiguous block of storage corresponding to it. The 
allocation of this memory is described in Section III. 

Next, there is the core memory in which reside the basic instruc- 
tions comprising the LISP interpreter, I/O routines, SUBRS, gar- 
bage collector, etc. This is the 16K of memory directly address- 
able by instructions. The contiguity of this memory block is also 
an illusion, but a very convincing one since it is implemented by 
the paging box. Core memory is also used for running compiled 
code, holding page buffers and temporary storage as shown in the 
figure. 




basic code 



/ compi 



iled code buffer 



virtual memory page 
buffer 



temp, storage 



LISP Core Memory Allocation 
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Because the LISP virtual memory is an illusion created by 

the LISP program, it is not possible to use it directly for I/O. 

That is, the hybrid processor, for example, cannot be instructed 

to read or write a large block of words using a LISP array 

because the array will in general be on the drum. Even if in 

core, it may be spread out over several non-contiguous page 

buffers. Therefore, it is necessary to allocate a contiguous 

block of core sufficient to hold the information to be transferred. 

But as can be seen from the diagram above, core is already 

completely allocated. The alternative is to create a fork with 

at least some independent memory and use it to do the I/O. The 

programs now written which use the fork logic allocate fork 

memory as shown in the figure. 

Main Fork 

Memory Memory 



37777 



20000 Q f 
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The shaded area, with addresses from 20000g to 37777 g, is 

common to both the main and the fork memory. The area from 

to 11111a in the fork is the independent memory used for I/O. 

Because the page buffers are necessary to effect references to the 
LISP virtual memory, and the page buffers and the I/O memory do 
not exist in the same forty:, a two-step process is necessary to 
move data between the virtual memory and I/O memory. This 
consists in first copying words from the source memory to a 
buffer area common to both forks then copying the buffer area 
to the destination memory. A program running in main memory is 
used to move data between the virtual memory and the buffer, and 
a program running in fork memory is used to move data between the 
I/O memory and the buffer. The LISP functions which perform these 
data transfers are compiled code and reside in the compiled code 
area when running. This area is common to both forks, and so a 
single function can contain instructions for execution in the 
fork as well as those for execution in the main program. The 
function must also contain space allocated for the buffer. The 
functions to transfer data to and from forks are called store fork , 
stfk , readfork , and rdfk, and are described in detail at the 
end of this section. The implementation details below should 
allow a user to define his own specialized functions for fork 
data transfer and running. 
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Implementation Details 



The information necessary to start a fork has been described 
generally above. The specific format prescribed by the time- 
sharing system for this information is shown below. This 
information is contained in a block of seven words called the 
fork table (sometimes called the panic table ) . 
















Program Counter 




1 


A Register 




2 


B Register 




3 


X Register 




4 
5 


— 


First Relabeling Register 
Second Relabeling Register 




6 


Status 





To start a fork, the controlling program must place the address 
of the fork table in the A register and execute a BRS 9 
instruction. The high order five bits of the A register also 
contain some control information which is used by BRS 9 . More 
details are available in the BRS manual. 

The BRS 9 causes the fork to commence operation as specified by 
the fork table, and both the main program and the fork are then 
running. When the fork is dismissed for any reason, the fork 
table is updated to show the latest contents of the central 
registers and relabeling. The status word indicates what caused 
the dismissal. 
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SPCELL+0 


PC 


1 


A / 


2 


B I 


3 


X ( 


4, 


RL1 I 


5 


RL2 \ 


6 


stat y 


7 




8 




9 




SPCELL+10 


CONSTANT 


11 


CONSTANT 


12 


FDDT RL1 


13 


FDDT RL2 


14 


FDDT ADR 


15 




16 




17 




18 




19 




SPCELL+20 


PC ""J 


21 


A J 


22 


B / 


23 


X I 


2k 


RL1 \ 


25 


RL2 ] 


26 


STAT J 



FIRST FORK TABLE 



ADDRESS OF FIRST FORK TABLE 

A REGISTER FOR BRS 9 FOR FIRST FORK 

RELABELING FOR FDDT 
START ADDRESS FOR FDDT 



SECOND FORK TABLE 
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There is a block of words in the temporary storage area of 
LISP available to the user for any purpose. The first location 
of this block is bound to the atom SPCELL. A portion of this 
block has been allocated for fork data as shown. 

Note that there are two fork tables. This allows one fork to be 
transferring data to or from the fork memory while the other 
runs the hybrid processor. The relabeling is the same for both. 

In some instances it is useful to have a fork containing DDT 
which can examine the running LISP. For example, this allows 
examination of compiled code in the binary program buffer. The 
following function provides that facility: 

ddt[] causes LISP to start a DDT which 

is looking at the running LISP. 
To continue LISP under this DDT, 
type 

30002 ;G. 
To return to LISP from DDT, hit 
2 rubouts or %F. Calling ddt[] 
while in a LISP running under 
DDT will cause a return to the 
higher DDT, not start a lower one. 
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Another function called fddt (for fork ddt ) Is available in the 
standard system to facilitate debugging of fork programs. 

fddt[] starts a DDT (the regular sub- 

system program) under LISP and 
sets it to look at the fork 
memory as determined by the 
contents of RL1 and RL2 in the 
first fork table. Two rubouts 
cause DDT to return to LISP. 
This DDT is distinct from the 
one described earlier, called by 
ddt[], which looks at the running 
LISP memory from the position of 
the LISP executive. 



Programmers writing fork programs should be aware of the complete 
fork structure of LISP as shown below in order to avoid 
complications. The user forks mentioned can be any that the 
user starts up. In addition, the user can call under LISP other 
940 subsystems using the function subsys. 



subsys[name;filel;file2] starts up a 9^0 subsystem as a 

fork under LISP. Only those sub- 
systems listed on the variable 
systems can be started. If filel 
is given, the subsystem accepts 
input from filel , otherwise tele- 
type. If f ile2 is given, output 
goes to f ile2 , otherwise teletype, 

utility [file] subsys [UTILITY; file] 
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The LISP executive fork performs very few functions and is 
run only when the interpreter dismisses itself. The TTY service 
fork, however, runs concurrently with the interpreter and is 
always waiting for TTY input. If a user fork is to do TTY input, 
the TTY Service fork must be terminated. A BRS 108 is satisfactory 
for this purpose. The TTY service fork is restarted by the 
interpreter fork whenever it is needed but not running. 
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Hybrid Processor and Fork Functions 

As mentioned earlier, the fork capability in LISP provides a 
practical way of driving the hybrid processor. This section 
describes a number of functions that have been written to provide, 
in various formats, input to and output from the fork's memory, which 

is the link between LISP and the hybrid processor. All of these 
functions are necessarily low-level, but for display applications, 
a very general set of higher level functions have been written, 
and are described in the section of the manual entitled Display 
Capabilities in LISP. This latter section can be referred to 
for a more extended writeup on the use of the hybrid processor 
and fork functions in a particular context. 

To run a process with the hybrid processor, one must first have 
a process number and appropriate devices assigned. The following 
functions are used for this purpose: 



assignp[pno] 



assigns process number pno for 
hybrid processor, returns pno or 
NIL if unable to assign. 



assignd[dev] 



assigns device dev , returns device 
number actually assigned or NIL 
if none available. 



unassign[ ] 



releases all devices and process 
numbers . 
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Before any fork operation can be performed, it is necessary to 
define the fork memory. This initialization is performed by 

forkinit[] initializes the fork 

which sets the contents of the relabeling registers of the first 
fork table to specify the memory configuration shown earlier in 
this document. It also sets up the two constants in 
SPCELL+10 and SPCELL+11. This initialization should be performed 
only once, but is not preserved through a SYSOUT-SYSIN, 

i.e., if you save your system and resume via SYSIN, you must 
perform another forkinit . 

The functions storefork and readfork described below permit 
transferring large blocks of data to and from any desired location 
in the fork's memory. However, the following conventions have 
been found to be extremely useful in communicating with the fork 
and the hybrid processor: 

1. The fork's memory is divided into a number of distinct, non- 
overlapping areas or tables. 

2. Each area is identified and referred to by its first location, 
called its handle . 

3. The contents of handle, i.e., the first cell in a table, is 
a pointer to the first unused word in the table. When the 
table is completed and given to the hybrid processor to run, 
this will be the first cell after the end of the table. 
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4. Commands for the hybrid processor begin at location 

handLe+1, and are contiguous. Data for the hybrid processor 
follows the commands, and continues to the cell whose address 
is contained in handle . 

To repeat, it is not necessary to adhere to these conventions to 
use the fork capabilities, although the functions described here 
are designed to make it easier to use the fork capabilities with 
these conventions. 



maketable[place;size] 



creates a table and initializes 
its pointer. If place is NIL, the 
table begins at location 200 (the 
fork memory goes from location 
to location 8192). If place is T, 
the. table begins immediately 
following the previous table 
(assuming it was also created by 
maketable ) . Otherwise, place must 
be a number and specifies the 
actual starting location of the 
table. Size is an optional 
argument which, if given, guarantees 
that the next table, if created 
by a call to maketable with 
place =T, will not overwrite this 
one. Essentially, it is a device 
for reserving a block of memory 
for a table without having to fill 
up the table. It enables the user 
to initially divide up the fork 
memory into several tables before 
transferring any data. 
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The value of make table is the 
handle of the table that was 
created. 

storefork[ap, incr, handl, rel,np] transfers the first n£ words 

from the array specified by ap_, 
an array pointer, into the fork's 
memory, beginning at locations 
handl+rel , and at every incr 
thereafter. If incr is not given, 
1 is used; if np_ is not given, 
arraysize[ap] is used; if handl 
is not given, free variable 
handle is used; if rel is not 
given, the contents of handl is 
treated as a pointer to the first 
unused word in the table and this 
latter location is the starting 
point for the transfer. In this 
latter case, the pointer is 
updated after the transfer is 
complete. Value is handl . 

Note: The error message (MACHINE SIZE TOO SMALL) means the user 
must return to the time sharing executive and change his machine 
size. The error message 

(ATTEMPT TO STORE/READ BEYOND END OF FORK) 
means the user has tried to reference a fork location > 8192. 
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Thus, to create a table and fill it with the arrays Al, A2, and 
A3, one must perform the following steps: 

MAKETABLEO 

200 

E (STOREPORK Al) 

200 

E (STOREFORK A2) 

200 

E (STOREPORK A3) 

200 

readfork[ap,incr,handl,rel,npJ transfers n£ points from the 

fork ! s memory beginning at loca- 
tion handl + rel , and at every 
incr thereafter, into ap_, an 
array pointer, rel must be given; 
if iH£H» handl , or n£ are suppressed, 
they are treated as for storefork . 
Value is handl . 

Note: the arrays for storefork and readfork must be arrays that 
contain unboxed numbers, since no boxing or unboxing takes place 
in either of these two functions. 

stfk[address,x] stores a single word into the fork 

at address . x should be a number 
which is then unboxed by stfk . 
Value is x. 

rdfk[address] reads a single word from the fork 

at address, and boxed this quantity 
to return a number. 
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Note: maketable , storefork, readfork , stfk, and rdfk all contain 
error checks for out of bounds references and machine size too 
small error conditions. In addition, storefork and readfork 
check to make sure that n£ is not too large for the array ap . 



hpstart[st,nt,lc,ld] 



starts up the hybrid processor. 
st is the starting location for 
hybrid processor information with 
commands coming before data. n_t 
is the iteration count for the 
data table, i.e., the number of 
times the data table is to be 
run (0=infinity) . lc is the 
length of the command table for 
the hybrid processor and Id the 
length of the data table. If Id 
is NIL, s_t is assumed to be a 
handle, and the first word a 
pointer as described earlier. In 
this case, hpstart computes Id . 
Thus, the user does not have to 
keep track of how. long his data 
table is. If ld^NIL, st points 
directly to the first command. 



hpstart uses pno as a free variable 
for the process number to be used. 
If a process is currently running, 
hpstart creates a new data block 
(BRS 132) and terminates the 
current data block (BRS 1^2) (see 
TSSS Manual). This means that 
running displays can be replaced 
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by new displays without any 
flicker. If no process is running, 
hpstart creates both a command 
block and a data block and starts 
a process. If it is necessary to 
start an operation with a new 
set of commands or iteration count, 
be sure to first do an hpstop . 

hpstop[] performs a BRS 138 which stops the 

hybrid processor. Uses pno as a 
free variable. 

hptest[] performs a BRS 137 which tests 

the status of the hybrid processor. 
Returns T if running, NIL if not. 
Uses pno as a free variable. 
Warning: hptest immediately 
following an hpstart may not return 
T: there is a slight time lag 
before the process actually gets 
going. 

hpwait[] performs a BRS 136 which dismisses 

user until the hybrid processor 
is finished. 
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hprun[ap,lc,np,iter,pno] 



drives the hybrid processor 
directly from LISP, i.e., this is 
the way displays were done before the 
fork capability was implemented. 
ap is an array which must lie on 
a single page, and therefore must 
be less than 253 in size. (note: 
all arrays of size less than 253 
do not necessarily reside on a 
single page - see hptable below.) 
lc is the number of commands, 
np the number of data words, with 
commands preceding data in the 
array, iter is the iteration 
count for the data table and 
pno the process number. 
hprun waits for the process to 
terminate before returning. 

hprun is primarily useful for 
short operations, such as reading 
a single A-D converter, 
because it does not require 
separate maketable , storefork , 
hpstart a and readf ork operations - 
the value(s) are returned directly 
into the array. 



hptable[m,n] 



creates an array analogous to 
(ARRAY M N) in such a way as to 
guarantee that the result is on 
one page. M must be less than 
253. Returns array as value. 
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brs[n,a,b,x] loads the A-register with a, the 

B-register with b, and the X- 
register with x and does a BRS n. 
Value is the A-register. For 
example (BRS 81 N) will dismiss a 
program for N milliseconds. 
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SECTION XVIII 

DISPLAY CAPABILITIES IN LISP 

Introduction 

At the present time the only display facility available on the 
BBN Research Computer is hardware which provides only a point by 
point display (e.g., no character or vector generators in hardware) 
Control of this display processor is achieved through the hybrid 
processor attached to the SDS 9*10. The display itself has no 
storage capability, therefore the image must be constantly 
refreshed by the hybrid processor from data stored in the com- 
puter's corp memory. To enable LISP programs to make efficient 
use of this display, functions have been written which provide 
a fairly sophisticated and general display language along with 
low-level routines for communicating with the CRT via the hybrid 
processor. We expect that later hardware additions to the display 
will make running the display more efficient, but may require a 
few changes in the user programs which describe and construct 
displays. 

Putting a display on the face of the CRT from within LISP is done 
in three distinct steps. The first of these involves constructing 
a display structure which specifies the points to be displayed. 
The second step is then to transfer the data corresponding to 
these points from LISP's memory into the fork's memory, (see 
Section XVII), from which it will be displayed. The third step is 
to initiate a program within the fork which starts up the hybrid 
processor; the hybrid processor will then maintain the display 
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on the face of the screen independent of what is taking place 
in the user's LISP program. 

The major effort in providing a display capability in LISP has been 
concentrated on the first step of the above operation, the gene- 
ration of a display structure. Most users need not even be aware 
of the details of steps two and three, beyond the fact that they 
must be done, and that some straightforward functions are provided 
to do them. For the interested, Section XVII discusses in greater 
detail the use of forks and the hybrid processor. The latter 
part of this section discusses the details of implementation of 
steps 2 and 3 above, and describes the operation of the lower 
level functions. 

Initialization 

In order for the user to actually display figures on the CRT, he 
must acquire for his use two D-A converters and a process number. 
The function start is available for this purpose. It assigns 
process number 1, and the two D-A converters in the list converterlst 
initially set to (0 1). Note: in most cases, the converters will 
be patched to the appropriate inputs, and the user can simply use 
start[]. However, in the event that the last person used the D-A 
converters for an application other than display, it may be 
necessary for the user to repatch the D-A converters or to find 
someone who can. 

Start calls start 1 which performs all initialization other than 
the assigning of process number and devices. If the user wishes 
to use the functions in the display package, but does not intend 
to actually display, he can perform startl[], and then proceed 
exactly as if he had the scope assigned to him. Function calls 
that would normally start a display will simply print DISPLAYING 
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on the teletype and continue. In this way several users can debug 
programs that use the display package, even though only one can 
be displaying at a time. 

The Display Language 

The display structure of step 1 is defined via the display language 
This language provides an aesthetic way of describing displays. It 
revolves around the concept of a figure , which in our terminology 
is a display gestalt. A figure can be composed of other figures, 
and, in turn, be a part of a larger figure, much the same as a 
list can be composed of sublists, and be a part of a larger list. 
The interpretation of a figure, and consequently the display it 
produces, depends on its type. Three of the more common figure- 
types are: 

1. Translate : if F is a figure, then (P X Y) is a figure 
consisting of P translated X units in the horizontal 
direction and Y units in the vertical direction. 

2. Scale : if P is a figure, (PS) is a figure consisting 
of P scaled by a factor of S, i.e., (F 1)EF. S can be a 
positive or negative, fixed or floating point number. 

3. Combine : if F, ... F are figures then (F, ... F ) is a 
figure consisting of the union of (the points of) the 
individual figures F-, through F . 

A primitive figure is an array consisting of X and Y 
coordinates in alternation. For example, the array containing 
the values (0 5 10 ... 45 0) specifies a horizontal line, 
10 points long, starting at (0 0) and ending at (45 0). If H is 
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such a line, and V a vertical line from (0 0) to (0 45), then 
the figure (H V (H 50) (V 50 0)) represents a square. Using 
SQ for square, we can define ROW as (SQ (SQ 50 0) (SQ 100 0) 
(SQ 150 0) ... (SQ 350 0)), and then CHECKERBOARD as 
(ROW (ROW 50) (ROW 100) ... (ROW 350)). 

The principal advantage of such a language is that it lends itself 
nicely to the recursive nature of LISP and list processing. Large, 
complicated displays can be conveniently broken down into small, 
subroutine-size chunks. A secondary advantage is the reduction 
in storage required for displays. For example the primitive 
figures H and D each require 20 array cells, SQ requires 
10 LISP words, and ROW, and CHECKERBOARD an additional 29 LISP 
words. Therefore, the entire checkerboard requires 68 LISP words 
and 40 binary program words, and specifies a display of 
2560 points. 

In addition to the three figure-types described above, the follow- 
ing figure-types are implemented in the display language :'(*) 

4. Scale : If P is a figure, (SCALE: F X Y) is a figure con- 
sisting of F scaled by X in the horizontal direction and 
Y in the vertical direction. (SCALE: F S S) is identical 
to (F S), a figure of type 2. However, figure type 4 
permits individual X and Y scaling. Note: reflection can 
be achieved by using a positive scale factor for one 
coordinate and a negative scale for the other. 

5. Plot : If A is a primitive figure, i.e., an array, then 
(PLOT: A) is a figure consisting of the values of A 
plotted as Y coordinates starting at X=0 with X advanced 
by 1 for each value of Y, i.e., the normal horizontal 



(*) An atom can be used to represent a complex figure; it will be 
evaluated and its value treated as one of the 11 figure types 
discussed here. 
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graph. Figure type 5 can be combined with type 1 and 
type 4 to produce a graph at any position, any scale. 
Note: values of A are treated as unboxed numbers. 

Other variations: (PLOT: A T) is a figure consisting of the 

values of A plotted as X coordinates starting at Y=0 

with Y advanced by 1 for each value of X, i.e., a 
vertical graph. 

6. Erase : (ERASE: M N) is a pseudo- figure, i.e., it does 
not itself transfer any points, but modifies previously 
transferred points. Its effect is to erase n words * 
starting from the M word in the top level superfigure, 

M and N > 0. For example, since ROW consists of 320 points 
or 640 words, the figure (CHECKERBOARD (ERASE: 1280 640)) 
would consist of a checkerboard with the third row erased. 

7. Restore : (RESTORE: M N) is a pseudo-figure which 
reverses the action of an ERASE pseudo- figure, i.e., 
(F (ERASE: M N) (RESTORE: M N)) is equivalent to F. 

8. Move : If F is a figure, (MOVE: F A-^ A 12 A 21 A 22 ) is a 

figure which is the linear transformation of F specified 

/All A12\ 
by the matrix/ J, AiJ positive or negative, fixed 

VA21 A22/ 
or floating point number. 

9. Rotate : If F is a figure, (MOVE: F 0) is a figure consist- 
ing of F rotated Q degrees. (MOVE: F 8) is identical to 
(MOVE: F C0S9 SIN9 -SING COS©). 



1 point = 2 words. 
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10. If A is an array, (A . N) is a primitive figure consisting 
of the first N points of A. This type of figure can be 
used anywhere a primitive figure can appear. Note that a 
figure of the form (F . N) where P is not a primitive 
figure, i.e., ((A 100 0) . N), is not permitted. 

11. Label : If F is a figure, then (LABEL: F label) is a 
figure that generates the same display as F. The purpose 
of this figure-type is to facilitate modification of 
selected subfigures in a large and complicated superfigure, 
After the Label: figure type has been interpreted and 
transferred into the fork its absolute X and Y coordi- 
nates, absolute X and Y scaling, relative position in the 
display table, and number of words it occupies in the 
display table are attached (by rplacd ) 3 in that order, 
following the label. 

New figure types may be defined by adding a definition of the form 
(name forml ... formn) to the list displaymacros . Before assuming 
that a figure is of type 1, 2, or 3, this list will be searched 
for a definition using assoc and car of the figure. If such a 
definition is found, forml through formn are evaluated. For 
example, one could define a figure type SHRINK: by adding to 
displaymacros 

(SHRINK: (DISPLIST1 (CADR FIG) X Y 

(FQUOTIENT SCALEX (CADDR FIG)) 
(FQUOTIENT SCALEY (CADDR FIG)))) * 



* displist is discussed on page 18.15 



18.6 



Generating Functions 

A generating function is one that constructs a display figure. 
Several are included in the display package. 

dline [x;y;dx;dy ;n] value is a primitive figure 

representing a line n points long 

starting at (x,v_) with increments 

(dx,dy). 

Thus from our checkerboard example, H=(DLINE 5 10) 3 
and V=(DLINE 5 10). 

dvector[x0,y0,xl,yl,n] value is a primitive figure repre- 
senting a line N+l points long 
starting at (x0,y0) and ending 
at (xl,yl). Note: dline is more 
efficient than dvector . 

dcircle[radius, dthetaj generates a circle of radius radius at 

[0,0]. dtheta represents the arc 
between points on the circle, i.e. 
360/dtheta = number of points. 
Value is primitive figure. 

Note: both dline, dvector and dcircle take two extra optional 
arguments a, and m. If given, the array a is used for the primi- 
tive figure, starting with postion m of the the array. In this 
way more than one primitive figure can be generated into the same 
array . 
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ds[s] 



generates (and displays) a figure 
for the list structure S in 
conventional box-notation. Its 
value is a generated symbol 
whose value is the figure itself. 



For example, DS((A B C)) will produce the display 



B 



■> 



C 



ds is equipped to handle circularities in both car and cdr direction 
Warning: since it marks each substructure to detect circularities, 
and subsequently restores the original structure, interrupting 
ds by rubout will cause the original list structure to be 
pe rmanent ly los t . 



dtree[tree] 



generates (and displays) a figure 
for the tree structure representa- 
tion of tree , i.e., car of each 
sublist labels the father node, 
cdr is treated as a list of the 
daughter nodes. For example, 
dtree[(S (NP (DET N) (PR P)) (VP V))] 
will produce the display 




DET 
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The value of dtree is a generated 
symbol whose value is the display 
figure, dtree is equipped to 
handle circularities in the car 
direction, i.e., common subtrees. 
Since it marks each subtree as it 
encounters them, and subsequently 
restores them, interrupting it 
by rubout will cause the original 
structure to be permanently lost. 

The variable trnpts initially set 
at 20, specifies the distance 
between adjacent levels of the 
tree. The variable trspacing , 
initially set at 3, specifies the 
minimum distance between any two 

adjacent nodes on the same 
level. If the width of the gene- 
rated tree is greater than the 
width of the scope, the tree is 
automatically scaled down in the 
horizontal direction. No scaling 
is performed in the vertical 
direction. However, deeper trees 
can be accommodated by resetting 
trnpts to a smaller value. 



18.9 



movefig[fig;opl;parl; . . .opn;parn] 



is an NLAMBDA nonspread function. 
It evaluates fig , but treats the 
rest of its arguments literally 
as operations and parameters, e.g., 

(MOVEFIG PIG UP 100 LEFT 100 ROTATE 30). 

Its value is a new figure corres- 
ponding to fig with the indicated 
operations having been performed. 
For the above example, this would 
be 

(MOVE: ((F 100) -100 0) 30) 

move fig is designed to free the 
user from remembering the 
various conventions of figure 
types 1 through 9. It recognizes 
UP, DOWN, LEF^, RIGHT, SCALE, 
SCALEX, SCALEY, ROTATE, MOVE and 
LABEL. For MOVE, the parameter 
should be the matrix of trans- 
formation. 
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Displaying Text 

A number of generating functions are available for character 
strings: dprint , dprinl , dprin2 , dspaces , dterpri , datom , and 
dischar . The first five perform functions analagous to the 
printing functions of the same name without the d. datom 
and dischar are lower level routines used by dprinl , but when 
called directly provide certain options not available through 
the higher level functions. These functions are designed to 
allow the user to treat the scope as a teletype, if he so desires. 

The size of the characters these functions generate is determined 
by the free variable charsize, initially set at 2. charsize is 
the spacing between points in a character. Since there are 
approximately 100 points per inch, and characters are 5x7 points, 
a character generated with charsize=2 would be . I"x.l4", which 
is approximately teletype sized. 

The free variables xorg and yorg determine the next character to 
be displayed, and correspond to the teletype position. They are 
numbers between -512 and 512, with (0,0) the center of the scope. 
xorg is adjusted by the above functions in accordance with the 
horizontal motion of the teletype carriage, yorg in accordance 

with the vertical motion of the paper. Their initial value 
determines the position of the first character. Their final value 
corresponds to the position on the scope where "printing" stopped. 

The free variables lorg and rorg determine the left and right 
"margins" of the display. Whenever a word (an atom) would be 
positioned at a point to the right of rorg , i.e., when xorg is 

greater than rorg , dterpri is called first. This function 
performs a scope "carriage return" by resetting xorg to lorg and 
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moving yorg down by 10*charsize. Similarly, the function dspaces 
"spaces" the display by changing xorg , but does not itself 
participate in the construction of any figures. 

To complete the analogy with printing, any carriage return or 
blanks that appear inside of an atom will have the obvious 
interpretation. Furthermore, dprint and dprin2 would cause this 
atom to be displayed in double quotes, while dprinl would not. 

dprinl has one additional feature not available on the teletype: 
subscripting and superscripting. The characters control-U and 
control-D have the effect of displacing yorg up or down by 
5*charsize. Thus the atom 

"XU2D + YU2D = ZU2D" 

where U and D denote control-U and control-D respectively would 
be displayed as 

X 2 + Y 2 = Z 2 

It is important to emphasize that all of these functions do not 
display, but merely generate figures . For example, for charsize =2, 
xorg= -400, and yorg= 4Q0, the value of datom[ABC] is the list 
(((a-L 2) -400 400) ((a 2 2) -386 400) ((a 3 2) -372 400)), where 

a,, a~, and a~ are primitive figures for the characters a, b, and c 

respectively. This figure can be repositioned, rescaled, combined, 
and transformed the same as any other figure. It is not displayed 
until it is transferred into the fork, step 2, and the hybrid 
processor is started, step 3. 
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dprint[x] 



dprin2[x] 
dprinl[x;prin2 ] 



performs dprin2[x] followed by 
dterprl[] and returns the value 
of dprin2 

dprlnl[x t] 

If xorg is greater than rorg , 
performs dterpri[]. Successively 
calls datom and dspaces on the 
components of x and on lpar , 
rpar , and period as required, and 
combines the values into a figure, 
which is returned as its value. 
The second argument of dprinl is 
used as the second argument to 
datom. 



dterpri[] 



dspaces[n] 



datom[atom;prin2;x;y ] 



sets xorg to lorg , yorg to 
yorg- 10*charsize. 

sets xorg to x o r g+ n * cha r s i'ze * 7 

generates a figure for atom at 
coordinates (x,y) if given, 
otherwise at (xorg, yorg). It uses 
chcon[atom;prin2] for the list of 
characters to be displayed. Thus 
if prin2=T, and atom is unusually 
spelled, double quotes will be 
supplied, datom recognizes and 
treats specially the character 
codes for blank, carriage return, 
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line feed, control U and control D. 
Otherwise, it calls dischar . 

dischar[c] c is a number used to reference 

the array masktable which contains 
35 bit masks for all of the tele- 
type characters. These masks are 
formed by mapping the 5x7 image of 
the character into a string of 35 
bits by starting at the lower left 
hand corner of the character and 
proceeding bottom to top, left to 
right, with a 1 indicating a point 
to be displayed. The first 21 bits, 
i.e., the leftmost three columns of 
the 5x7 image, are left justified 
to form the first word of the mask. 
The last 14 bits, also left justi- 
fied form the second word. These 
are stored in location 2c-l and 2c 
in masktable . For example, location 
103 in masktable is 00403770Q, loca- 
tion 104 is 0040200Q, corresponding 
to the mask for the character T, 
which has ASCII code 52. 

The first time a particular charac- 
ter is encountered, a primitive 
figure is generated for it, and 
stored in the array chart able . 
Subsequent use of this character 
will not require regeneration. 
Thus, the generation of figures 
for text is essentially a table 
of lookup process. 
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Mote: arraysize[chartable]=12 8, and 
not all of these are taken by 
existing symbols, so the user can 
define new symbols by placing an 

appropriate mask in masktabl e via 

seta. 



Decoding Figures 



Step 2 of producing a display consists of transferring the data 
corresponding to the points in a display figure into the fork's 
memory. This is done by the function displist . 

displist [fig;place ;handle] if handle=NIL, maketable[place] 

is called followed by 
storeforkLca] which transfers into 
the fork the commands necessary to 
display points. Then displistl is 
called to decode fig . The value 
of displist is handle. 

h _____ 

displistl [fig; x;y ; scalex;scaley ] 

performs the decoding of fig. 

The normal way of using dis plist is to call it with place -NIL or T 
In the first case, the display table will begin at the lowest 
location in the fork's memory. In the second case, it will begin 
at the first location after the previous table. In both cases, 
the value of displist is the information that will be required 
by drun , the function that starts the display. For more details, 
see the description of make table and the discussion of handles in 
Section r.'II. 
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If displist is called with handle not equal to NIL, maketable and 
store fork are not called. This is one way to add a figure to a 
oreviously existing table. For example, displist [figl] followed by 
displist[fig2;NIL;x] where x is the value of the first call to 
displist , i.e., the handle, is equivalent to 

displist[list[figl;fig2]], since list[figl;fig2] is a figure of 
type 3, combine . 

Driving the Display 

Once the points have been transferred into the fork, the user can 
start the display by calling the hybrid processor and specifying 
appropriately the number of commands, number of points, number of 
iterations, etc. This is performed by the function drun . 

drun[handl;nt J If handl is NIL, handl e is used. 

handle has a top level binding of 200, 
the first available location in 
, the fork's memory and the value 

of displist when place=NIL. If 
nt is NIL, is used which is 
interpreted as infinity by the 
hybrid processor. If start [] 
had been called, drun starts the 
display, otherwise it prints 
DISPLAYING. 
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display [fir;] Executes displist [fig] , followed 

by drun, and returns a gensym 
whose value is fig. For example, 
E (DISPLAY (DATOM (QUOTE TESTING) ) ) 
will generate the figure for this 
atom, transfer it into the fork, 
start the display, and return a 
gensym whose value is the figure. 
This can be used for subsequent 
calls to displist . 



It is important to emphasize that displist only transfers points 
into the fork, and drun only calls the hybrid processor. One can 
execute several calls to displist before displaying anything and 
then switch rapidly back and forth from one display to another by 
calling drun with different values for its first argument. Simi- 
larly, one can execute a displist and a drun , and then be perform- 
ing another displist while the display is running. If this latter 
displist should happen to overwrite the display table for the 
first one, the new points will be seen as soon as they are trans- 
ferred, and the entire display will seem to melt into the new one. 
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Low- level Functions 

The preceding discussion has presented all of the user-level 
display functions. These will be sufficient for most users and 
most applications. The following sections will describe the 
lower level functions, and the details of the present implementa- 
tion. To make effective use of these functions, the programmer 
should have a greater knowledge of the computer hardware, time- 
sharing system, and LISP implementation. Furthermore, changes 
in the display hardware will result in changes, additions, and 
deletions to these functions. That is, programs which use these 
functions directly will probably be affected by changes in hard- 
ware or low-level software. Programs which use the higher-level 
functions will not. 

Hybrid Processor and Fork Functions 

If the reader has not already done so, at this point the portion 
of Section XVII entitled 'Hybrid Processor and Fork Functions 1 
should be read. Briefly, this section discusses the use of the 
fork capability in LISP for driving the hybrid processor and 
the conventions for communicating with the fork. In particular, 
the reader should review the organization of the fork's memory 
into tables , and the use of the function make table . The functions 
assignp , assignd , unassign , forknit , hpstart , hpstop , hptest , 
hjpwait, and store fork are also of interest for display applications 
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Storepoints 

Storepoints , like storefork , is a function for transferring data 
from LISP's memory to the fork's memory. It takes among its 
arguments ap_, handl , rel , and n£ and treats them similarly to 
storefork : transferring the first n£ words of ap_ into the fork's 
memory beginning at location handl+rel +3. The 3 reflects the 
presence of the pointer in the handle and the two command words. 
Therefore, rel is relative to the first point in the table, not 
the first word. If n£ is not given, arraysize[ap] is used; if 
handl is not given, the free variable handle is used; if rel is 
not given, the contents of handl is treated as a pointer to the 
first unused word in the table and this latter location is the 
starting point for the transfer. In this latter case, the pointer 
is updated after the transfer is complete. The value of store- 
points , like storefork , is handl . 

However, storepoints , unlike storefork , expects that its array 
contains the x and y coordinates, in alternation, of points to be 
displayed, and operates in a pair-wise fashion. It also includes 
among its arguments several options specifically tailored for 
display applications: 

storepoints [ap ; dx ; dy ;sclx;scly ; handl; rel ;np] 

transfers np_ or arraysize[ap] 
words from ap_ into fork. dx and 
dy are the translations and 
sclx and scly the scale factors 
for the x and y coordinates, 
respectively. storepoints moves 

each pair of words into the fork f s 
memory, at the same time multi- 
plying by sclx , or scly , and 
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adding dx or dv_, and converting 
to the format required by the 
hardware. If dx or dv_ are not 
given, is used. If sclx or 
scly are not given, the free 
variable scalex or scaley are 
used. These are initially 
set to 1. sclx or scly 
may be positive or negative, fixed 

or floating point numbers. The 
elements in ap_ should be LISP 
numbers between -512 and 512,- and 
are unboxed and shifted appro- 
priately before being transferred. 

Another option available in storepoints allows blanking out and 
subsequently restoring selected points. This is achieved by 
giving storepoints as its first argument, NIL, for erasing, or T 
for restoring (instead of an array). Starting at the appropriate 

location, the appropriate number of points will then have their 
low order bits set to 1, if erasing, or set to 0, if restoring. 
When the "blink" switch for the scope is on, points with low 
order bits set to 1 are not displayed. If the display were being 
run at the time of the operation of storepoints , these points 
would instantaneously disappear or reappear. Similarly, the 
effect of a moving display can be created by overwriting portions 
of a table while it is being displayed. Note that appending 
to a table, i.e., calling storepoints with rel=NIL, can never 
cause an immediate change in a display. This is because the 
call to the hybrid processor which starts a display must, in 
advance, specify how many points are to be displayed. Any 
additions to the table will be seen only when another drun 
executed. The only way to achieve the effect of points 
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spontaneously appearing in a display while it is in progress 

is to initially store "invisible" points in the display, 

i.e., points with low order bit set to 1., and then overwrite these 

or turn them back on while the display is running. 

Plotting Graphs 

Many graphs can be specified more efficiently than by a collection 
of x-y coordinates as required by storepoints . It is often 
possible to simply give a sequence of values for one axis, and the 
first value and increment between successive values for the second 
axis. This reduces by half the amount of storage required to 
represent the graph. The function plot array is provided for this 
purpose. 

plot array [ ap ; dx ; dy ; s clx ; s cly ; vert ; handl ; rel ;np ] 

transfers np_ or arraysize[ap] 
words from ap_ into twice that 
many words in the fork's memory. 
The interpretation of handl and 
rel is the same as for storepoints , 
The numbers in ap_ are interpreted 
as y-coordinates , unless vert= T. 
The value of the other coordinate 
starts at and is advanced by 1 
for each point, dx and dy_ are 
the translations and sclx and 
scly the scale factors for the 
x and y coordinates so that any 
positioning or scaling can be 
achieved. If dx or dv_ are 
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not specified, is used. If 
sclx or scly are not given, scalex 
and scaley are used. If the ap_ 
contains all boxed numbers, plot- 
array will unbox them. 

plot array is used by displist for figures of the form (PLOT: — ). 
Moving Points 

The function movepoints described below provides an alternate, 
more efficient way of effecting linear transformations of 

two dimensions such as rotation and shearing. This entails per- 
forming modifications on the corresponding points after they have 
been stored into the fork's memory, rather than modifying a LISP 
array or several arrays and then storing the modified arrays into 
the fork using storepoints . 

mo vepoint s [mat ri x ; dx ; dy ; handl ; re 1 ; np ; from ] 

If handl is not given, handle is 
used. If rel, dx, or dv_ is not 
given, is used. Modifications 
begin at handl+rel+ 3 and proceed 
through np_ words, if n£ is given, 
otherwise through entire table, 
i.e., up to the location specified 
by the pointer in handl . 

matrix is a list of the form 
^ a ll a 12^ ^ a 21 a 22^ where a j* 
are the elements of a two by two 
matrix, and may be positive or 
negative, fixed or floating point 
numbers. For each pair of x-y 
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coordinates, the new value of x is 
given by 

x ' = a ll* x + a 12* y + dx 
and the new value of y by 

y ! = a 21 *x + a 22 * y + dy 

The state of the low order bit of 
x and y is not disturbed so that 
invisible points are transformed 
along with visible ones but remain 
invisible. 

If matrix=NIL, ((1 0) (0 1)), 
the identity matrix, is used. 
If matrix= N, a number, 

((COS N -SIN N) (SIN N COS N)) 
is used, i.e., the effect of the 
transformation would be to rotate 
the points N degrees . 

If from is given, the old values 
of x and y are taken from the table 
whose handle is from . The new ones 
are stored in the table specified 
by handl. Essentially this allows 
you to move from one table to 
another and to perform a transfor- 
mation if desired. 



Movepoints is used by displist for figures of the form 
(MOVE: — ). 



18.23 



SECTION XIX 
ADVISING 

The operation of advising gives the user a way of modifying a 
function without necessarily knowing how the function works or 
even what it does. Advising consists of modifying the interface 
between functions as opposed to modifying the function definition 
itself, as in editing. break , trace , breakdown , and follow are 
examples of the use of this technique: they each modify user func- 
tions by placing relevant computations between the function and 
the rest of the programming environment. 

The principal advantage of advising, aside from its convenience, 
is that it allows the user to treat functions, his or someone 
else's, as "black boxes," and to modify them without concern for 
their contents or details of operations. For example, the user 
could modify sysout so that it did not write any new files, i.e., 
files that did not already appear in this file directory. This 
could be done by: 

ADVISE (SYSOUT (COND 

((INPUT (INFILE U)) (CLOSEF U)) 
(T (PRINT (CONS U (QUOTE (NOT FOUND))) T) 
(RETURN NIL))) 

As with break , advising works equally well on compiled and inter- 
preted functions. Similarly, it is possible to effect a modifica- 
tion which only operates when a function is called from some other 
specified function, i.e., to modify the interface between two 
particular functions, instead of the interface between one function 
and the rest of the world. This latter feature is especially use- 
ful for changing the internal workings of a system function. 
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Consider the following obscure bug in prettyprint (which has since 
been fixed): if a prog had two labels for the same statement, and 
the first label had more than four characters in it, no spaces 
would be printed between the two labels. Consequently, when the 
function was loaded back in, only one label would be read: 
the concatenation of the two labels that were printed. This con- 
dition could have been remedied by: 

ADVISE ((SPACES IN PRINTPROG) 

(COND ((ZEROP U) (SETQ U 1)))) 

Advice can also be specified to operate after a function has been 
called, in which case the value of the function is bound to the 
variable VALUE, as with BREAK. For example, execution of all com- 
mands to the LISP editor is performed under an errorset in the 
executive editor function edite . Frequently the user may type in 
a long command with a small error in it, and would prefer to be 
able to correct the command rather than having to retype it. The 
user could modify the editor to automatically save a command when- 
ever an error occurred during its execution by performing 

ADVISE ((ERRORSET IN EDITE) AFTER 

(COND ((NULL VALUE) (SETQ LASTCOM C)))) 

since the value of errorset is NIL if and only if an error occurs 
in the evaluation of its argument. 

Note that advising spaces or errorset would have affected all calls 
to these very frequently used functions, whereas advising (SPACES 
IN PRINTPROG) and (ERRORSET IN EDITE) only affects calls to spaces 
from printprog or errorset from edite. 
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Advise 

Advise is a function of four arguments: name , when , where and what . 
name is the function to be modified by advising, what is the modi- 
fication, or piece of advise, when is either BEFORE or AFTER with 
the obvious interpretation. (If not given, BEFORE is assumed.) 
WHERE is optional and can be used to specify exactly where in the 
list of advice statements the advise is to be placed, e.g., FIRST or 

(BEFORE (ADVICE CONTAINING PRINT)), or (AFTER 3), meaning after 
the third piece of advice, or even (FOR ALL (ADVICE CONTAINING 
RETURN)). If where is specified, advise calls the editor to find 
and insert the advice at the appropriate location. Otherwise, 
the advice is inserted after any previous modifications. The 
structure of a function after it has been modified several times 
by advise is given in the following diagram: 
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The corresponding LISP definition is: 

(LAMBDA arguments (PROG (VALUE) 
(SETQ VALUE (PROG NIL 
advicel 



advicen 
(RETURN fn arguments ) ) ) ) 
advicel 



advicem 
(RETURN VALUE))) 

where fn is the name of the function (generated by advise ) whicb- 

— — « jig «— — •— ■— ^— — 

now contains the original, unadvised definition. 

Note that the structure of a function modified by advise allows a 
piece of advice to bypass the original function by using the LISP 
function RETURN. For example, if the LISP form 
(COND ((ATOM X) (RETURN Y))) appeared among the advice BEFORE 
a function, and this function was entered with X atomic, Y would 
be returned as its value, i.e., VALUE would be set to Y, and 
control passed to the advice, if any, to be executed AFTER the 
function. If this same piece of advice appeared AFTER the function, 
Y would be returned as the value of the entire advised function. 



* fn is stored on the DroDerty list of the function name under the 
property ADVISED. 
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The advice (COND ((ATOM X) (SETQ VALUE Y) ) ) AFTER the function 
would have a similar effect but the rest of the advice AFTER 
the function would still be executed. 
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advise [name, when, where, what] name is the function to be advised, 

when=BEFORE or AFTER, where 
specifies where in the advice list 
the advice is to be inserted, and 
what is the piece of advice. Both 
when and where are optional argu- 
ments, in the sense that they can 
be omitted in the call to advise . 
In other words, advise can be 
thought of as a function of two 
arguments: [name, what], or a function 
of three arguments: [name, when, what] 
or a function of four arguments: 
[name, when, where, or what]. Note 
that the advice is always the last 
argument . 

If name is of the form (fnl IN fn2), 
chngnm[fn2,fnl] is first performed 
as with break, and then fnl-IN-fn2 
is used in place of name. 

If * name is non-atomic, every func- 
tion in name is advised with the 
same values (but copied) for 
when , where, and what . 

If name is broken, it is unbroken 
before advising. 
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If name is not defined, an error 
is generated. 

If name is being advised for the 
first time, an appropriate 
S-expression definition is created, 
and the original definition stored 
on a gensvm . and the gensvm stored 
on the property list of name under 
the property ADVISED. 

name is added to the list 
advisedfns . 

The modification is inserted in 
the appropriate position indicated 
by where in the list of advice 
either BEFORE or AFTER the function 
depending on when . If where=NIL, 
the advice is added to the end 
of the advice. If where=FIRST 
or TOP, it is inserted in front 
of the advice. Otherwise, where 
is treated as a location command 
for the expanded editor, e.g., 
BEFORE 3), 
(AFTER (ELEMENT CONTAINING PRINT)). 

(when where what) is added to 
the front of a list of all calls 
to advise for name which is kept 
on the property ADVICE. 

Value of advise is name. 
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unadvise[x] 



advisedump[x] 



is a non-spread NLAMBDA a la 
unbreak . It takes an indefinite 
number of functions to be restored 
to their unadvised state. 
unadvise[] or unad vise [ALL] will 
cause all functions on advisedfns 
to be unadvised, unadvising 
consists of restoring the original 
definition, removing the properties 
ADVISE and ADVISED from the pro- 
perty list, unbreaking if the 
function is also broken, and if 
the function is an alias, i.e., 
created by an advise (fnl IN fn2) 
call, the higher level function 
in which it appeared is also 
restored. 

advisedump is the function that 
is called when an expression of 
the form (ADVISE fnl . . . fnm) 
appears in the third argument to 
prettydef . If car[x] is not 
atomic, eval[car[x]] is used 
instead of x. Then for each 
function on x that has a property 
ADVICE, the reverse of the property 
value is put on the property 
READVICE. Two def lists are 
written: one for every function 
that has a property ALIAS, and 
one for every function with 
property READVICE. 
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readvise[name] is designed to be used in con- 

junction with advisedump and 
prettydef for dumping advised 
functions and then loading and 
restoring them to their advised 
state. If name is of the form 
(fnl IN fn2) or there is a pro- 
perty ALIAS on the property list 
of name , the appropriate chngnm 
if first performed, readvise 
then calls advise for each 
modification on the list stored 
under the property READVICE. 

The value of readvise is name . 

Note: if a function has both the property READVICE and the property 
ADVICE, unadvise will first move the reversal of the property 
value of ADVICE onto READVICE before it removes the former. Thus 
if the user readvises, then executes additional calls to advise, 
and then unadvises, all the advice would still be dumped when the 
function was prettydef-ed. 

In summary, advise puts advice on the property ADVICE, advisedump 
takes it from ADVICE, or else from READVICE. readvise uses the 
advice on READVICE. unadvise removes the property ADVICE but 
first moves ADVICE to READVICE provided both properties are 
present. No function removes READVICE. 
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cadvice[fns] fns is a list of advised functions 

to be compiled with their advice. 
cadvice performs the appropriate 
modifications to their property 
lists before and after calling the 
compiler. After compilation, the 
function can still be unadvised, 
in which case the compiled code 
will be lost. If the function has 
a property EXPR this property value 
will be preserved through the com- 
pilation. 
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SECTION XX 

AUTOMATIC ERROR CORRECTION IN LISP 

Introduction 

A surprisingly large percentage of the errors made by LISP users 
are of the type that could be corrected by ; another LISP programmer 
without any information about the purpose or application of the 
LISP program or expression in question, e.g. misspellings, certain 
kinds of parentheses errors, etc. We have implemented into the 
BBN LISP system a DWIM package, short for Do-What-I-Mean, which 
is designed to facilitate the correction of these type of errors. 
DWIM is called automatically whenever an error occurs in the 
execution of a LISP program (provided the user has first enabled 
this feature), and then proceeds to try to correct the mistake. 
The following output is representative of the kinds of corrections 
the program will handle. 
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- DEFINEQ((FACT (LAMBDA (N) 

(COND ((ZEROP ;N9 1) ((T (TIMS N (FACTT 8SU81 N] 

(FACT) 

- PRETTYPRNTC CFACCT3 

=PRETTYPRINT 

= FACT 

( FACT 

(LAMBDA CN) 
(COND 

((ZEROP N9 1 ) 

CCT (TIMS N (FACTT 8SUB1 N) ))))))) 
NIL 

-FACTO) 
EDITING FACT ... 
N9 >>--> N) 
EDITING FACT ••• 

(COND -- CCT.--)>) >>--> CCOND -- CT --)> 
T IMS=TIMES 
FACTT=FACT 
EDITING FACT ... 
SSUB1 >>--> CSUB1 
6 . 

-PRETTYPRINTCCFACT)) 

C FACT 

CLAMBDA CN) 
CCOND 

C (ZEROP N) 

1 ) 
(T (TIMES N (FACT (SUB1 N))))))) 
N IL 



In this example, the user first defines a function PACT, of one 
argument, N, whose value is to be N factorial. The function con- 
tains several errors: TIMES and PACT have been misspelled. The' 
9 in N9 was intended to be a right parenthesis but tne teletype 
shift key was not depressed. Similarly, the 8 in 8SUB1 was in- 
tended to be a left parenthesis Finally, there are two left 
parentheses in front of the T that begins the second clause in the 
conditional, instead of the required one. 
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After defining the function PACT, the user wishes to look at its 
definition using PRETTYPRINT, which he unfortunately misspells. 
Since there is no function PRETTYPRNT in the system, an UNDEFINED 
FUNCTION error occurs, and the DWIM program is called. DWIM in- 
vokes its spelling corrector, which searches a list of functions 
frequently used (by this user) for the best possible match. Finding; 
one that is extremely close, DWIM proceeds on the assumption that 
PRETTYPRNT meant PRETTYPRINT, informs the user of this, and calls 
PRETTYPRINT . 

At this point, PRETTYPRINT would normally print (FACCT NOT PRINTABLE) 
and exit, since FACCT has no definition. This is not an error 
condition, so DWIM would not be called by LISP. However, it is not 
what the user meant . 

In order to handle these type of situations, when the user first 
enables the DWIM facility, ADVISE is called to modify selected 
system functions. For example, PRETTYPRINT is advised that when 
given a function with no definition, it should call the spelling 
corrector. Similarly, DEFINE is advised to add the names of any 
new functions defined by the user to the spelling list of user 
functions. Thus, with the aid of DWIM, PRETTYPRINT is able to 
determine that the user wants to see the definition of the function 
FACT, and proceeds accordingly. 

The user now calls his function FACT. During its execution, five 
errors are generated, and DWIM is called five times. At each point, 
the error is corrected, a comment made of the action taken, and the 
computation allowed to continue as if now error had occurred. Fol- 
lowing the last correction, 6, the value of FACT(3), is printed. 
Finally, the user prints the new, now correct, definition of FACT. 
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In this particular example, the user was shown operating in a 
mode which gave the DWIM system the green light on all corrections 
Had the user wished to interact more and approve or disapprove of 
the intended corrections at each stage, he could operate in a 
different mode. Or, operating as shown above, he could have at 
any point aborted the correction; or signalled his desire to see 
the results of a correction after it was made by typing a ? on the 
teletype. 

Each different user may want to operate with a different "confi- 
dence factor," a parameter which indicates how sure DWIM must 
be before making a correction without approval. Above a certain 
user-established level, DWIM makes the correction and goes on. 
Below another level, DWIM types what it thinks is the problem, 
e.g., PRTYPNT = PRETTYPRINT ?, and waits for the user to respond. 
In the in-between area, DWIM types what it is about to do, pauses 
for about a second, and if the user does not respond, goes ahead 
and does it. The important thing to note is that since an error 
has occurred, the user would have to intervene in any event, so 
any attempt at correction is appreciated, even if wrong, as long* as 
the correction does not cause more trouble than the original to 
correct. Since DWIM can recognize the difference between trivial 
corrections, such as misspellings, and serious corrections, such 
as those involving extensive editing, bad mistakes are usually 
avoided. When DWIM does make a mistake, the user merely aborts 
his computation and makes the correction he would have had to 
anyway . 



20.4 * 



Enabling DWIM 

To enable the DWIM package, perform DWIM[T]. DWIM will type 
"SET MODE B,N, OR E" , for BEGINNER, NOVICE, or EXPERT. (These 
will be explained later.) Respond by typing either B, N, or E; 
DWIM will complete the rest of the mode name.* To disable DWIM, 
perform DWIM[ ] . This is guaranteed to return the system to a 
pristine state. 

Error Correction 

Once DWIM has been enabled, errors that normally generate either 
UNBOUND ATOM or UNDEFINED CAR OF FORM messages (undefined function 
call from interpreted code), instead call the functions f ixatom 
and fixfn, respectively. If an attempted correction is aborted 
by typing control-R, or if the user indicates to DWIM not to pro- 
ceed with the correction, or if DWIM cannot fix the error, the 
action taken is exactly as though DWIM had not been enabled, i.e. 
the system goes into a break, as described earlier in the manual. 

The general strategy followed by both fixatom and fixfn ^ is to 
return the correct S-expression for the desired evaluation and 
continuing the computation, and also to repair the cause of the 
error . DWIM in general is more cautious about making corrections 
to user functions than making corrections to S-expressions typed 
into evalquote or to break. 

Unbound Atoms 

Fixatom is currently programmed to handle six different types of 
unbound atom errors. 

1. If the first character of the atom is an 8 , DWIM assumes 
that the b was intended to be a left parentheses, and calls 
the editor on the expression in which the atom appeared. 



* Alternatively, call DWIM with mode as argument, e.g. DWIM[E]. 

20.5 



It is assumed that the user did not notice the 8, or attempt 
to correct for it. In other words, the user typed in the 
same number of right parentheses and in the same places, as 
he would have had the 8 actually been a left parentheses. 
For example, (LAMBDA (N) 8C0ND ((ZEROP N) 1) (T (TIMES N 
(PACT (SUB1 N]. If the unbound atom did not appear in 
another expression, e.g. if the user typed 8CAR X) into 
break for evaluation the appropriate expression is obtained 
and evaluated. 

2 . If the first character of the unbound atom is f DWIM 
assumes that the user (intentionally) typed 'ATOM for 
(QUOTE ATOM) and makes the appropriate change. If the 
unbound atom is just ' , DWIM assumes that the user typed 
'(LIST) for (QUOTE (LIST)) and proceeds accordingly. 

3. If the last character in the atom is 9 a DWIM assumes the 
9 was intended to be a right parentheses and operates in 
a manner analagous to case 1. 

4. If 8 appears as a character inside the atom , DWIM assumes 
the 8 was intended to be a left parentheses, splits the 
atom into two parts, and takes the appropriate corrective 
action, e.g. (CONS X8CDR Y]. 

5. If the unbound atom is the name of a low level function , 
e . g . APPEND, CONS, SUBST, etc., (anything defined before 
PRETTYDEF) DWIM assumes a left parentheses was omitted 
before the atom, but that the corresponding right paren- 
theses was typed. In general, for parentheses errors, 
DWIM always assumes the error was undetected by the user 
and that no attempts were made to correct for it during 
input. If the user notices a parentheses error of the 
type handled by DWIM while typing in the expression, he 
should ignore it . 

6 . For all other unbound atoms, DWIM assumes that there has 
been a spelling error and calls the spelling corrector 
(described below). The spelling corrector is given a 
list of possible choices consisting of all variables set 
by rpaqq , plus, in the case the error occurred in a user 
function, a list of lambda variables and prog variables 
for that function. 
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Undefined Functions 

Fixfn is currently programmed to handle six different types of 



errors. 



1. If the undefined function is T , and it appears in an 
expression of the form (COND — (— (T ))), or (COND — 
((T — ))), or immediately following a COND as in (COND — ) 
(T --), DWIM assumes the T was meant to start the last 
clause in the conditional and makes the appropriate change. 

2. If the undefined function is not atomic, DWIM assumes an 
extra parenthesis was put in e.g. (CONS ((CAR X) Y] or 
(COND (((ZEROP N) 1) (T (TIMES N (FACT (SUB1 N] . 

3. If the undefined function has a binding, and is three or 
fewer characters in length, DWIM assumes an extra paren- 
thesis was put in e.g. (CONS (X Y)). 

i|. If the undefined function is F/L, DWIM assumes the user 
"(intentionally) typed (F/L expression) meaning (FUNCTION 
(LAMBDA (X) expression)), or if (F/L arg-list expressionl 
... expressionm)), meaning (FUNCTION (LAMBDA arg-list 
expressionl ... expressionm)). 

5. If the undefined function contains an 8 , DWIM assumes a 
left parentheses was intended. If the error occurred on 
input to evalquote, e.g. «- EDITF8F00) , the appropriate 
form is evaluated. If the error occurred inside of 
another expression, e.g. (ADD18CAR X), the undefined 
function is split into two parts and the 8 treated as a 
left parentheses, as in 4. of fixatom . 

6. For all other cases, DWIM assumes a misspelling has occurred 
and the spelling corrector called. If the depth is greater 
than 3 3 the spelling corrector is given a list of low-level 
functions such as addl , atom , cons , etc., i.e. those typically 
used inside a function. If the depth is less than 3 S the list 
contains top-level functions such as defineq , prettydef t 
makefile, load, etc. In both cases, the lists include all 
functions defined by the user with defineq, including those 
loaded from files. 
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User Modes - Interaction with DWIM 

There are currently three modes of operation in DWIM: BEGINNER, 
NOVICE, and EXPERT. These modes control the setting of certain 
parameters that in turn determine the amount of interaction for 
the various errorsdiscussed earlier. Essentially, DWIM always 
asks the user for approval when in BEGINNER mode, and its mes- 
sages are more explicit and verbose. In NOVICE mode, DWIM asks 
the user for approval for action to be taken when the error occurred 
in a user function, as opposed to an expression typed by the user 
to evalquote or break. DV/IM rarely asks the user for approval in 
EXPERT mode, with the exceptions noted below. 

Interaction on Parentheses Errors 

Errors involving parentheses errors, i.e. errors of type 1,3,4 and 
5 of fixatom and errors of type, 1,2,3, and 5 of fixfn require 
editing. DWIM types an error message: ...UNBOUND ATOM or . . . 
UNDEFINED FUNCTION in BEGINNER mode, and U.B.A. or U.D.F. in 
NOVICE mode. This is followed by the atom or function name, and 
its location (i.e. IN function ) if the error occurred in a user 
function. DWIM then requests permission to make the correction. For 
example, ...UNDEFINED FUNCTION 8SUB1 IN FACT FIX ? 

At this point, the correction that DWIM intends to makes has already 
been determined by the type of error; DWIM is simply asking for user 
approval. If the user types Y, for YES, DWIM will proceed with the 
correction. If the user types N, for NO, or hits control-R the cor- 
rection is aborted. If the user types f, not only DWIM but also the 
subsequent break is aborted, i.e. it is equivalent to typing control-R 
followed by +.* If the user types anything else, the editor is called, 
for the user to edit the expression himself. 

When the editing has been completed, DWIM will type the transformat- 
ion that was performed, e.g. 8SUB1 >> — > (SUB1, and then CONTINUE ? 



* retfromLnJ where n is position of first errorset previou s to call 
t0 faulteval is performed. If none, retfrom[0] is performed. 
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If the user types Y for YES, the computation continues, and the 
appropriate expression is evaluated. The only possible cause of 
trouble in continuing involves an error of the form (COND — ( — 
(T — ))). Here the value of the conditional should have been the value 
of the expression immediately preceding the (T — ). This express- 
ion must be reevaluated since its value is no longer around. If it 
cannot be reevaluated without producing a harmful effect, the user 
should type N for NO. The cause of the error will have been fixed, 
but the computation will not continue. Instead an error will be 
generated, and the system will go into a break. If the user types 
anything other than Y or N, DWIM calls the editor again to allow 
the user to look at the changes it has made. After exiting from 
the editor in the normal way by typing OK, the user is again asked: 
CONTINUE ?, etc. 

If the user is operating in NOVICE mode and the error did not occur 
in a user function, or if the user is in EXPERT mode, DWIM normally 
does not ask for approval before attempting a correction. In this 
case DWIM simply types EDITING function... or EDITING... and pro- 
ceeds with the correction. There are two exceptions, however. 
For errors of type 2 and 3 in fixfn e.g. (CONS ((CAR X) Y)) and 
(CONS (X Y)), DWIM will always ask for approval, because these may 
be the expressions the user had intended: the undefined function 
error may have tjeen generated because of a logical problem, 
e.g. X was bound to a function that was not defined. 

If the user is operating in a mode that does not require DWIM to 
interact with him, he can still signal DWIM that he wishes to 
examine the changes that were made before continuing the computat- 
ion by typing any character while DWIM is editing. When editing 
has been completed, DWIM will then operate exactly as though the 
user were in BEGINNER mode. 

If DWIM was unable to make the correction, or if the user aborted 
the editing by typing control-R ( WARNING in this case some changes 
may have been made before the user aborted), DWIM will type COULDN'T. 
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Interaction on Spelling Errors 

Whenever an unbound atom or undefined function error occurs that 
is interpreted as a misspelling, DWIM types an error message fol- 
lowed by the atom or function identification as described earlier. 
The spelling corrector then attempts to select the best match with 
the list of correct spellings that it has been given. If no 
reasonable match can be found , the spelling corrector types the 
offending word, followed by = ?, e.g. 
U.B.A. F00 
POO = ? 

The user can then type the correct word. If he mistypes again, the 
spelling corrector iterates. The only way to leave the spelling 
corrector is to give it a suitable word, or to abort by typing 
control-R or +. If the user does type in a suitable word, i.e. a 
BOUND ATOM or a DEFINED FUNCTION, the S-expression in which the 
misspelling occurred is corrected, and this word is added to the 
spelling list so that it will be considered as a possible correct 
spelling for future mistakes. In the case of an UNBOUND ATOM, the 
user can also type in a non-atomic form which is then used to cor- 
rect the S-expression, e.g. 

U.B.A. F00 

F00 = (CAR FIE) 

If the spelling corrector finds a word or words which are reason- 
able matches , it types them followed by ?, e.g. 
F00 = F001 or F002 ? 

The acceptable answers to this question are t, Y, for YES (only if 
just one word matches); N, for NO, in which case WHAT THEN ? is 
typed and the user is in the same situation as when no suitable 
match was found; D, for DELETE, in which case these words are 
eliminated from the spelling list and will not be considered in 
the future; or a number, to indicate which of the various words 
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typed is correct. The user is not allowed to type in the correct 
word in response to a question of the form F00= F001 or F002 ? 
He can only type + , y, N, D, or a number . 

If the user is operating in NOVICE mode and the error does not 
occur in a user function, or if the user is operating in EXPERT 
mode, the spelling corrector does not require interaction if the 
match is "good enough." There are two parameters that affect this 
determination. These are CFACT1, initially set at .5, and CFACT2 
initially set at .8. If the match is better than CFACT2 in reli- 
ability, i.e. at least 80% sure, the spelling corrector makes the 
correction types it, and goes on, e.g. F000 = F00. If the match is 
better than CFACT1 but less than CFACT2, the spelling corrector 
types what it thinks is the correct spelling, and then waits a 
specified number of milliseconds, as determined by the parameter 
DELAYTIME (initially set at 4000) . If the user types any character 
during this time, the spelling corrector goes into interactive mode 
as described earlier. Otherwise it makes the correction and goes 
on. 

Summary of Interaction bv Morton 

Parenthesis error in user function FACT, e.g. 

(FACT 8SUB1 N) 

BEGINNER ...UNDEFINED FUNCTION 8SUB1 IN FACT FIX ? 

NOVICE ...U.D.F. 8SUB1 IN FACT FIX ? 

EXPERT EDITING FACT. . . 

unless type 2 or 3 of fixfn, in which case 
same as NOVICE mode. 

Parenthesis error in user typed expression; e.g. 
«-E (FACT 8SUB1 F00) 

BEGINNER ...UNDEFINED FUNCTION 8SUB1 FIX ? 

NOVICE EDITING. . . 

EXOERT EDITING... 

unless type 2 or 3 of fixfn 

Note: for input like <- EDITF8F00) to evalquote, a subcase of error 
5 of fixfn , DWIM requires no interaction in any mode. 
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Spelling error in user function, e.g. (FACCT (SUB1 N)) 



BEGINNER 

NOVICE 

EXPERT 



...UNDEFINED FUNCTION FACCT IN FACT 
FACCT= *** ? 

. . .U.D.F. FACCT IN FACT 
FACCT= *** ? ■ ■ 

FACCT=FACT(IN FACT) if certainty > CFACT2 

FACCT=FACT(IN FACT) and pause for specified time 

if certainty > CFACT1 . If 
no input, make correction 
and continue. 

. . .U.D.F. FACCT IN FACT 

FACCT= *** ? if certainty < CFACT1 or if 

two choices equally good 



Spelling error in user expression, e.g. + FACCT (4) 



BEGINNER 



NOVICE 



...UNDEFINED FUNCTION FACCT 
FACCT= *** ? 

FACCT=FACT if certainty > CFACT2 

FACCT=FACT 



and pause for specified time 
if certainty > CFACT1 



EXPERT 



...U.D.F. FACCT 
FACCT = *** ? 

same as NOVICE 



if certainty < CFACT1 or if 
two choices equally good 



(*** represents list of possible candidates, if any) 
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Private Modes 

If the user wants to define his own mode, presumably to combine 
certain features of BEGINNER, NOVICE, or EXPERT, or to change the 
confidence thresholds, he must add the definition of his mode to 
the end of modelst . Each mode is a list consisting of a single 
identifying character (hence do not use B, N, or E), followed by 
the rest of the mode name, followed by a list of dotted pairs of 
variables and values. For example, the first entry on modelst is 
(E XPERT (GREENLIGHT . T) (REDLIGHT) (CPACT1 .5) (CFACT2 .8) 
(UDF . "U.D.F.") (UBA . "U.B.A.")). 

If the variable greenlight is T, as in EXPERT mode DWIM never asks 
for interaction, (with the few exceptions mentioned earlier). If 
both grreenlight and redlight are NIL, as in NOVICE mode, DWIM asks 
for interaction only for errors involving user functions. If 
redlight is T, as for BEGINNER mode, DWIM always asks for inter- 
action. The variables udf and uba are the error messages printed 
out for undefined function and unbound atom errors respectively. 

Other uses of the spelling corrector 

As mentioned in the introduction, the spelling corrector is used 
in the DWIM package to correct certain misspellings that would 
not cause LISP errors. This has been accomplished by advising 
certain system functions, such as prettyprint to consult the 
spelling corrector when given an argument that does not "make sense" 
in the context Q f the operation they perform. Userwords is a list 
of words that may contain the spelling the user intended. This 
list is built up by certain other system functions, e.g. defineq , 
rpaqq which have been advised to add to this list. Thus if DWIM 
is enabled and the user loads a file, all functions defined and 
variables initialized in the file will be added to userwords. 
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System Functions Advised by DWIM 

EDITF - if argument is (NOT EDITABLE), but has a non-atomic 

value, editv is called. If it has a non-null property 
list, editp is called. Otherwise it is treated as the 
name of a function on userwords . 

EDITV - if argument is (NOT EDITABLE), it is treated as the 
name of a variable on userwords . 

EDITP - if argument is (NOT EDITABLE), it is treated as an 
atom on userwords with a non-null property list. 

BREAKJ0 if function is not defined, it is treated as the name 
of a function on userwords . 

UNSAVEDEF - if function is not defined, it is treated as the name 
of a function on userwords . 

PRETTYPRINT - if function is not defined, it is treated as the name 
of a function with an S-expression definition on 
userwords . 

In addition, after they have finished operating, EDITF, EDITV, 
EDITP, DEFINEQ, 3REAK0,. UNSAVEDEF, and RPAQQ all add their arguments 
to userwords as well as to the approoriate snelling lists for 
error correction 

Load is advised to maintain two lists: a spelling list of user files, 
( filesplst ) and a list of user files with the functions and variables 
they contain ( filelst ) t derived from the first and third argument to 
prettydef . * makefile consults filesplst to correct the spelling 
of its argument, and editf , editv , and editp add their argument 
to filelst under the name of the appropriate file. The function 
newfiles can then be used to produce an updated version of any 
files that have been changed. 

newfiles[flg] does makefile for every file on filelst that 
has been modified. If flg=T, the files are 
also listed. 



(*) This assumes that the file was created by makefile, p. 14.21 
i.e. that its name is of the form /Nname/. 



20.14 



If the user wishes to modify his own or other system functions, the 
following two functions will be useful: 

addspell[x;flg] Adds x to userwords , and, if fig = T, to 

the spelling list for variables, otherwise 
to both spelling lists for functions. Sets 
lastword to x* If 2L is already on userfns , 
no action is taken. 

misspelled? [x;fn;splst] If fn is not NIL and fn[x] is not NIL, 

value is x, i.e. x was not misspelled. 
If x is NIL, value is lastword e.g. after 
defining a function, you can edit it by 
simply performing editf[]. Otherwise 
spelling of atom is corrected using splst , 
if given, otherwise userwords . If spelling 
correction is aborted by control-r, value 
is x. If + is typed to spelling corrector, 
control is returned to errorset prior to 
misspelled ? 

As an example of the use of these functions, the following advising 
operations are performed by DWIM. 

ADVISE (DEPINEQ AFTER (MAPC VALUE (FUNCTION ADDSPELL))) 

ADVISE (RP A QQ AFTER (ADDSPELL XT)) 

ADVISE (UNSAVEDEF (SETQ X (MISSPELLED? X (FUNCTION FNTYP))) 
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NOFIX 

The user may not want to have DWIM bother to operate on certain 
types of errors. To facilitate this, DWIM calls the function 
nofix , of no arguments, before attempting to make any corrections. 
If noflx returns T, the correction is aborted, nofix is currently 
defined as (LESSP FAULTD FAULTDEPTH), with FAULTDEPTH set to -1. 
If the user wanted to disable DWIM for errors occurring near the 
top level, or just inside of a break, he simply needs to set 
FAULTDEPTH to an appropriate value, e.g. 5. The user can prescribe 
more complicated conditions for aborting corrections by advising 
nofix . For example, the user might prefer to retype any misspelling 
shorter than four characters in length. He would then advise nofix 



ADVISE(NOFIX (AND (ATOM FAULTX) (LESSP (NCHARS FAULTX) 4))) 

Of course, such operatives require more intimate knowledge of the 
operation of DWIM. For this, contact W. Teitelman. 
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SECTION XXI 



PRINTSTRUCTURE 



In trying to work with large programs, a user can lose track of 
the hierarchy which defines his program structure; it is often 
convenient to have a map to show wfyich functions are called by 
each of the functions in a system. If fn is the name of the top 
level function called in your system, then typing in 
printstructure[fn] will cause a tree printout of the function-call 
structure of fn. To describe this in more detail we use the 
print structure program itself as an example. 
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*-Pt< I NTS Ik UC I UK EC PR IN I SI RUCTURE) 

PRINTSTRUCTURE PROGSTRUC PRGSTRC PRGSTRC 1 PRGSTRC! 

PRGSTRC 
PRGSTRC 
NOTFN 
PROGSTRUC 
CALLS 1 NOTFN 

CALLS2 CALLS 1 
PRGSTRC 
PRINTSTRUCTURE 
MAKECIRC MAKECIRC 
TREEPRINT TREEPRINT1 

TREEPRINT 
VARPRINT TREEPRINT1 

PRINTSTRUCTURE [FN, FILE; XyDONELST, NODES? 3 

PROGSTRUC CFN,l); Y , Z, FLG, VARS 1 , VARS2; DONELST3 

p HGSTRC CX*HEAL)J Y,Z; VARS 1 > FN, DONELST, D/FLG3 

PRGSTRC 1 CLJ A,B,Y; Y > VARS 1, VARS2 3 

NOTFN [FN; D Ep . 3 

CALLS 1 CADR, U; M,N,X, Y,FLG> VI, V2,FLG; VARS1, INTZRO, VARS2 3 

CA LLs2 ex; ; 03 

MAKECIRC CXJ X; NODES 3 
TREEphint CX,N; Z; 3 
TREEPRINT1 CX,N; ; ] 

VARPRINT CX ; X,Y,N; 3 
PRIN1 STRUCTURE 
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The upper portion of this printout is the usual horizontal version 
of a tree. This tree is straightforwardly derived from the defi- 
nitions of the functions: printstructure calls progrstruc , itself, 
makecirc, treeprint , and varprint . progstruc in turn calls 
prgstrc and calls , prgstrc calls prgstrcl itself, and notfn. 
prgstrcl just calls itself and prgstrc . Note that a function 
whose substructure has already been shown is not exnanded in its 
second occurrence in the tree. 

The lower portion of the printout contains information about the 
variables that are used in each of the functions, printstructure 
is a function of two arguments, fn and file . It binds three 
variables internally: x, donelst , and nodes . (Variables are 
bound internally by either progs or open lambda-expressions.) 
makecirc has only one argument, x, and it also binds x internally. 
It uses the variable nodes as a free variable. 

In addition to the five functions appearing in the above output. 
printstructure calls many other low-level functions such as 
getd , car , list , nconc , etc. The reason these do not appear in 
the output is that they were defined "uninteresting" by the user 
for the purposes of this analysis. Two functions, firstfn and 
lastfn , and two variables yesfns and nofns are used for this 
purpose. Any function that appears on the list yesfns is of 
interest, any function appearing on nofns is not. Otherwise, all 
non-compiled functions are deemed interesting, and only those 
compiled functions between the two limits established by firstfn 
and lastfn . For example, first fn[ edit f] and lastfn[bo] (tjie last 
function in the edit package) followed by printstructure[editf] 
will cause the structure of the editor to be printed out with 
only those functions that actually are part of the edit package 
appearing in the printout. 
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Three other variables, notrace, quotefns , and prdepth also affect the 
action of printstructure . Functions that appear on the list notrace will 
appear in the tree, assuming they are "interesting" functions as 
defined above, but will not themselves be traced, i.e., analyzed. 
Functions that appear on quotefns are traced, assuming they are 
"interesting," but when they appear as car of a form, the rest of 
the form is not analyzed. For example, if the function prinq were 
defined as (NLAMBDA X (MAPC X (FUNCTION PRIN1 ) ) ) and the form 
(PRINQ NOW IS THE TIME) appeared in a function being analyzed, 
prinq would appear in the tree, but NOW, IS, THE, and TIME would 
not be noted as free variables if prinq were included in the list 
of quotefns . prdepth is a cutoff depth for analysis. It is inially set 
to 100. 

printstructure has incorporated in it the necessary information 
for analyzing non-standard forms such as cond, prog and selectq . 
It is also capable of analyzing compiled or interpreted functions 
equally well. In the case of compiled functions, printstructure 
will automatically analyze any functions generated by the compiler, 
such as those caused by compiling forms beginning with ersetq , 
nlsetq , or function . 

If printstructure encounters a form beginning with two left paren- 
theses in the course of analyzing an interpreted function (other 
than a COND clause) it notes the presence of a possible £arentheses 
error by the abbreviation P.P.E., followed by the function in which 
the form appears and the form itself, as in the example below. 
Note also that printstructure detects functions, i.e., atoms 
appearing as CAR of a form, that are not defined, printstructure 
is thus a useful tool for debugging. 
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-PRETTYPRINK (F00>) 

( FOO 

(LAMBDA (X) 
CCOMD 

(X (FOOl X)) 

(T ((CONS X (CAR X) )))))) 
N IL 
-PR I NTSTRUCTUREC FOO) 



FOO 




FOOl 

CONS 
CAR 


FOO 




CX; ; ] 


FOOl 




IS NOT DEFINED. 


P .P.E. 


IN 


FOO - ((CONS X (CAR X))) 


FOO 
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Printstructure Functions 

print structure [ f n , f ile ] 



analyses structure of fn and 

stores result on property list of 

fn under property PRINTSTRUCTURE. 

The form of this result is a list 

of two elements, the second of 

which is the tree representation 

of the structure, and the first 

a list consisting, in alternation, 

of the functions that appear on 
the tree, and a variable list vlst 

for that function. CAR of the vari- 
able list is a list of variables 
bound in the function; CDR is those 
variables used freely in the function, 



Thus in the printstructure [printstructure] example given earlier 
the value of the property PRINTSTRUCTURE would be: 

((PRINTSTRUCTURE ((FN FILE X DONELST NODES)) PROGSTRUC 
((FN D Y Z FLG VARS1 VARS2) DONELST) PRGSTRC 
((X HEAD Y Z) VARS1 FN DONELST D FLG) ... 
VARPRINT ((X X Y N))) tree) 

Possible parentheses errors are 
indicated by a non-atomic form 
appearing where a function would 
normally occur, i.e., in an odd 
position of the list. It is 
followed by the name of the func- 
tion in which the P.P.E. occurred 
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If file=NOTHING, no output is 
produced. If file=SCOPE or 
DISPLAY, the structure is dis- 
played on the scope. In this 
case, the result of the analysis 

contains a third element, the 
display figure that was generated 

by dtree . For any other value of 

file, output is to that file. 



treeprint[x;n] 



varprint [x] 



first fn[fn] 



The value of print structure is fn . 

when given a tree representation 
of the structure, (see dtree, p. 18.8) 
e.g., cadr[getp[fn,PRINTSTRUCTURE]]. 
treeprint prints the tree in the 
horizontal fashion shown in the 
examples above. Used by 
printstructure . 

when given the list of functions 
and their variables, i.e., 
car [getp[fn, PRINTSTRUCTURE]], 
varprint prints the lower half 
of the examples shown above. 

fn is the name of a compiled 
function. If fn=T, lower boundary 
is set to 0, i.e., all compiled 
functions will pass this test. If 
fn=NIL, lower boundary set at end 
of bpspace, i.e., no compiled 
functions will pass this test. 
Otherwise boundary set at fn. 
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lastfn[fn] 



calls [fn] 



if fn=NIL, upper boundary set at 
end of bpspace, i.e., all compiled 
functions will pass this test. 
Otherwise boundary set at fn. Thus 
to accept all compiled functions, 
perform firstfn[T], lastfn[NIL] 

returns a list of three elements: 
a list of all (interesting) 
functions called by fn, a list of 
variables bound in fn, and a list 
of variables used freely in fn, 
e.g., calls[prgstrc]= 
((PRGSTRC1 PRGSTRC NOTFN PROGSTRUC) 
(X HEAD Y Z) (VARS1 FN DONELST FLG)) 



vars[fn] 
freevars[fn] 



cdr[calls[fn]] 



cadr[vars[fn] ]=caddr [calls [fn] ] 



allcalls[fn,tr] 



prints fn IS CALLED BY: and returns 
list of all functions that call fn 
in the tree tr. If tr Is atomic, 
cadr[getp[tr;PRINTSTRUCTURE]] Is 
used. Example: 



- ALLCALLSCPRGSTRC PR INTSTRUCTURE ) 

PRGSTRC IS CALLED BY: 

(PROGSTRUC PRGSTRC1 PRGSTRC CALLS1 > 
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Follow 

Follow is a function that enables the user to dynamically watch 
the flow of computation through a collection of functions. Follow 
uses print structure to analyze the hierarchy of functions and to 
display a tree structure on the scope. Every function appearing 
in the tree is then modified to appropriately adjust the display 
when it is entered. Whenever one of these functions is entered, 
a circle is drawn around the corresponding node in the display, 
and a dotted path is displayed from the function that called it. 
For example, if the user performs: firstfn[editf ] , lastfn[bo], 
follow[editf J and then calls the editor, he can watch the editor 
as it executes his commands. (Follow is not in current system but 
can be loaded from file /(FLIP)CFOL/. ) 

follow[fn;flg] performs print structure [fn] 

and then modifies (using break) 
all functions in the resulting 
tree to appropriately update the 
display. If flg=NIL and follow[fn] 
has been done previously, follow 
does not regenerate the display, 
instead it obtains it from the 
property FOLLOWED on the property 
list of fn. unbreak restores the 
functions to their unmodified 
state. 

followspeed initially set to 0, 
controls the delay time, in clock 
ticks, between changes in the dis- 
play. It can be set to slow down 
what might otherwise be a confusingly 
rapid succession of changes in the 
display. 
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TIME 



SECTION XXII 



MISCELLANEOUS 



time[x;n;g] 



Time executes the computation x, 
n number of times, and prints out 
the number of cons es , total time/n 
if nj^l and computation time per 
iteration. Garbage collection 
time is not included, i.e., it is 
subtracted out. If n is NIL, it is 
set to 1. If g is T, garbage col- 
lection time is also printed. 

Example : 

TIME ((CONS NIL NIL) 1000 T) 

GARBAGE COLLECTION 

2458 CELLS 

1 CONSES 

12/1000=0. 12000E-01 SECONDS 

GARBAGE COLLECTION TIME: 23 SECONDS 

(NIL) 

TIME ((PRETTYDEP (QUOTE (POO)))) 

CONSES 

9.0. SECONDS 

(FOO) 
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date[] Obtains date and time from system 

and returns it as single atom in 
format M mm/dd/gg hhmm:ss". 

where mm is month, dd day, gg year, 
hh hours, mm minutes, ss seconds, 
e.g., "02/21/68 1352:41" 

clock[n] for n=0 value of time of day 

clock, i.e., number of 
seconds since midnight 

for n=l time of day user logged in 

for n=2 number of seconds of com- 
pute time since user 
logged in (garbage 
collection time is 
subtracted off) 

for n=3 time spent in garbage 
collections 

Value of clock is in "ticks." 

tickps[] Number of ticks per second, 

usually 50. 
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BREAKDOWN 

Breakdown is a function that produces an analysis of computation 
time by function, although it can be used for an analysis of 
CONSes, drum references, garbage collection time, or any other 
single numerical quantity. The user calls breakdown giving it a 
list of functions of interest. These functions are modified so 
that they keep track of the "charge" assessed to them. The func- 
tion results gives the analysis of the statistic requested as 
well as the number of calls to each function. Sample output is 
shown below. 



- BREAKOOWNCSUPERPRINT SU8PRINT) 

(SUPERPRINT SUBPRINT) 

-PRETTYDEFCFOOFNS /FQQ/ (STOP)) 

F OOFNS 

-RESULTSC) 

FUNCTIONS TIME # CALLS 

SUPERPRINT 6.30 731 

SUBPRINT 3.94 274 

TOTAL 10.22 100 5 

ML 



To add or remove functions from those being monitored, the user 
must call breakdown giving it the entire new list of functions. 
However, breakdown!! ] can be used for simply zeroing the counters 
associated with the function already being monitored. 
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To use breakdown for some other statistic, the user must set 
three variables: breakdown form , the quantity of interest, 
e.g., (CLOCK 2) or (CONSCOUNT), label , e.g., TIME or CONSES, and 
interp , (optional) which is a function that will be applied to 
the statistic to produce the numbers printed by results . Thus, 
since the value of (CLOCK 2) in the above example is in clock 
ticks, to convert to seconds, interp had been set to 

(LAMBDA (X) (PQUOTIENT X (TICKPS))). 

Whenever breakdown is called with b reakdownf orm having a non-null 
value, breakdown performs the necessary changes to its internal 
state to conform to the new analysis. In particular, if this is 
the first time an analysis is being run with this statistic, the 
compiler is called to compile the charging function. When break- 
down is through initializing, it sets breakdownform back to. NIL. 
Subsequent calls to breakdown will use the new analysis until 
breakdownform is again set. Sample output is shown below. 



-SET(BREAKDOWNFORM (CONSCOUNT)) 

(CONSCOUNT) 

-SET(LABEL CONSES) 

CONSES 

-SET( INTERP NIL) 

NIL 

-BREAKDOWN(MATCH CONSTRUCT) 

(A0272 COMPILING) 

(A0272 (BOX BDY) (BDLST BDPTR) 5) 

(MATCH CONSTRUCT) 
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-PILOTCT) 

PROCEED: 

FLIPCCA B C D E F G H C Z> (•• $1 •• #2 • •> <•• #3 ••)) 

CABDEFGHZ) 

>RESULTS() 

FUNCTIONS CONSES # CALLS 

MATCH 32 1 

CONSTRUCT 47 1 

TOTAL 79 2 
N IL 



Each time breakdown encounters a new value for breakdownform , 
it saves the corresponding value of label , interp , and the com- 
piled charging function. Thus, if breakdownform is set to a form 
already encountered, it is not necessary to also set label and 
interp , nor will the compiler be called. 

To restore functions modified by breakdown to their original 
state, use unbreak. 



TIMEX 



Timex is a timing function that reports statistics on number of 
function calls, drum references, wraparounds, etc., as well as on 
computation time and conses. It accepts input from the teletype 
for eval, and prints an analysis after each input. Exit is 
achieved by typing OK at which point timex also gives the distri- 
bution of drum references analysis. Sample output is given 
below. 
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TIMEXO 



> (PRETTYDEF (QUOTE FOOFNS) (QUOTE /F00/ ) (QUOTE (STOP))) 

2 4 CONSES 

1 0.06 SECONDS 

1 WRAPAROUNDS 

1 5762 MAPPED STORES 

40923 TOTAL MAPS 1.64 SECONDS 

5 7 TOTAL DRUM REFS 0.97 SECONDS 

1 1 DRUM WRITES 0.19 SECONDS 

5 161 FUNCTION CALLS 7.74 SECONDS 

1 5 BP DRUM READS 



> (COMPILE (QUOTE (MAKEPDQ))) 

L ISTING? 

F 

(OUTPUT FILE) 

N 

(MAKEPDQ COMPILING) 

GARBAGE COLLECTION 



1 906 FREE WORDS 
(MAKEPDQ (F) NIL 5) 
GARBAGE COLLECTION 
6 90 FREE WORDS 

2 761 CONSES 

3 4.56 SECONDS 
2 WRAPAROUNDS 

5 7510 MAPPED STORES 
2 15088 TOTAL MAPS 
2 40 5 TOTAL DRUM REFS 
2 66 DRUM WRITES 
S90 FUNCTION CALLS 
8 6 BP DRUM READS 



8.60 SECONDS 
40.88 SECONDS 
4.52 SECONDS 
12.58 SECONDS 
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>0K 



DISTRIBUTION OF DRUM REFERENCES 

ARRAY SPACE 1458 

L 1ST SPACE 665 

PNAME SPACE 31 

PARAM PUSHLIST 16 

CONTROL PUSHLIST 8 

VALUE CELLS 61 

PROPLIST CELLS 50 

FUNCTION CELLS 63 

P NAMES & HASH CELLS 110 

BOXED NUMBERS 36 



DISTRIBUTION OF DRUM REFERENCES WRITE-ONLY 

ARRAY SPACE 4 

L 1ST SPACE 174 

P NAME SPACE 5 

PARAM PUSHLIST 15 

CONTROL PUSHLIST 4 

VALUE CELLS 20 

PROPLIST CELLS 1 

FUNCTION CELLS 1 

P NAMES & HASH CELLS 25 

BOXED NUMBERS 36 
N IL 



If the first argument to timex is not NIL, it is treated as a 
list of inputs for eval exactly as though they had been typed by 
the user. If the second argument is T, the analysis after each 
evaluation is suppressed. The third argument, also optional, is 
a number given to time as its second argument and controls the 
number of times each individual input is to be evaluated. 
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Enlarging the System 

The BBN LISP system uses techniques which allow the system code, 
i.e., all of the functions described in this manual, plus those 
described in the FLIP manual, to be shared by all users. In 
addition to this (approximately) 90K of system code, each user 
can acquire another (approximately) tyQK 940 words of private 
memory; this allows the user about 20K of LISP words. The LISP 
system can be enlarged up to a maximum size of 256K by reassemb- 
ling it. However, an individual can effectively acquire additional 
private memory in the existing system by "flushing" some of the 
system code. The function flushcode is provided for this purpose. 
Its effects are not reversible, but the flushed material can be 
reloaded from the appropriate disc files. 

flushcode[from;to;flg] flushes all binary programs between 

from and to. If to = NIL, flushes 
all binary programs from from to the 
end of binary program space. If 
flg=T, it prints names of functions 
being flushed. from and to can be 
numbers corresponding to function 
definitions (*), or they can be 
any atom on the list flushpoints , 
which contains the starting loca- 
tions of various independent sub- 
systems such as display , flip , 
compiler etc. If to=T, just the 
subsystem from is flushed, e.g. 
flushcode [printstructure; T] will 
flush just printstructure . These 
systems have been loaded so that 
all functions used by any parti- 
cular system are loaded before it. 
The user can thus safely flush any 
subsystems following the ones 



(*) (LOGAND (GETD FN) 377777Q) 
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he is planning to use. Of course, 
independent systems such as display , 
compiler , etc. can always be 
flushed without affecting the 
operation of other systems. 

When flushcode is called with 
to=NIL, the reclaimed space will 
be noted by storage . However, 
if the user makes a "hole" in his 
binary program space, no change 
will be observed in storage . 
However, when a request is made 
for an array or binary program 
allocation that can fit in the 
hole, the space will be taken 
from there. Bpspace is a list of 
elements of the form (N M) 
corresponding to the user holes. 

Note: the user should not flush 
the same area twice, as it will 
then appear twice on bpspace and 
hence be used twice. 
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Dumping Circular List Structure 

It is often important to save list structures so that reloading 
will maintain common substructure. In particular, this is critical 
for circular lists which cannot be saved any other way. The func- 
tion saved described below allows a user to dump a representation 
of a set of structures onto a file; later, reading them back in 
with the function loadcl obtains an isomorphic copy of the 
original structures. 

The algorithm for dumping is a variation of one first suggested by 
Minsky for garbage collection using secondary storage (described 
in Bobrow, "Storage Management in LISP'). Each structure to be 
saved is traced, and as each new LISP word is seen, it is marked 
by placing a mark in its car and a number in its cdr . The number 
indicates where this word will be reloaded. The mark is a gensym 
created for marking all words which are to be considered part of 
this set of structures. The dumped representation consists of 
triples for each word in the structure(s ) : its new (relative) 
address, its car and its cdr, both of which are either atoms or 
the new addresses of structure. Note that this process destroys 
the structures so traced. 



s ave c 1 [ Is t ; f i le ; ident ] 



1st is a list similar to the third 
argument to prettydef , e.g., 

(A B (PROP Q R S) (DEF FN1) STOP) 

will specify saving the values of 
A and B, the entire property lists 
of Q, R, and S, and the definition 
of FN1. STOP specifies closing 
file. 
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If file is initially open, writing 
is continued. If it is not open, 
it is opened and the date printed. 
If file=NIL (omitted) the primary 
file is used. 

ident, the third argument to 
saved , is used by the marking 
process. If it is omitted, it is 
supplied by saved . In this case, 
the structures dumped by this call 
to saved will not have common 
substructures with any previously 
dumped. To preserve common sub- 
structures across several different 
calls to saved , give for ident 
the value of the previous call to 
saved . For example, if the user 
performs 

SAVECL(W0RDS1 /FL1/) 

(A0005 135*0 

SAVECL(W0RDS2 /FL2/ (A0005 135*0) 

(A0005 2938) 

and subsequently reloads both files 
using loadcl , he will get a struc- 
tural copy of the items specified 
by W0RDS1 and W0RDS2. If he re- 
loads just /FL1/, he will get a 
copy of only those items specified 
in WORDS 1. 
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loadcl[file; ... filen] is a CPEXPR*. Each argument is 

a file name corresponding to a 
file generated by saved , loadcl 
uses a contiguous block of storage 
beyond that currently in use to 
load all structures in these files, 
changes the internal state of the 
user's LISP to bring this block 
within list space bounds, and 
then initiates a garbage collection 
to clean things up. Note: if 
loadcl is interrupted before 
finishing, strange pointers may 
be left around in regular list 
space. 

An additional advantage of the 
saved - loadcl process is that 
all restored lists are linearized 
in storage, and compacted onto as 
few pages as possible. 
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GROUP 



Group is a function for parsing lists as LISP forms. It takes a 
list such as (CONS CAR X CDR RPLACA X Y), and tries to make a 
single LISP form out of it, in this case returning 
(CONS (CAR X) (CDR (RPLACA X Y))). The function nargs is used to 
determine the number of arguments for each function encountered 
in the list. Group allows less than that number to be specified, 
i.e., group[(CONS CAR X)]=(CONS (CAR X)), but if an expression 
cannot be grouped without some function exceeding its number of 
arguments, group returns NIL, e.g., group[(CONS CAR X CDR Y Z)]=NIL 
If the user has functions with extra arguments in their definition 
that are never used, he can indicate the true number of arguments, 
for the purposes of group , by putting this number on the func- 
tion's property list under the property NARGS. Group looks here 
before calling nargs . This is also the way to handle functions 
that take an indefinite number of arguments, such as list . Since 
nargs[LIST]=l, by definition, group[(LIST X Y CAR Z)]=NIL. How- 
ever, if you first perform put [LIST;NARGS ;100] , then 
group[(LIST X Y CAR Z)] will yield (LIST X Y (CAR Z)) as desired. 
Group is not in basic system but can be obtained by loading file 
/(FLIP)CPILOT/ 
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ARM 



Arm is a function for modifying the effect of control-H. Its 
name derives from the expression "to arm an interrupt," which is 
essentially what arm does, arm takes as its argument a function, 
or the name of a function, and modifies interruptl so that when 
a control-H is typed following other teletype input, the arming 
function (the argument to arm ) is called. If it returns NIL as 
its value, the normal (INTERRUPTED BEFORE ... ) consequence of 
typing control-H occurs. However, if it returns a non-null value, 
the computation continues exactly as though the user had typed 
control-H followed by OK. For example, if F00 is defined as 

( F00 

(LAMBDA NIL 
(COND 

(CREADP) 

CSELECTQ (READC) 
CD CDRUN) 

T) 
(S (HPSTOP) 

T) 
NIL))))) 

and arm[F00] is executed, then whenever the user types a D 
followed by a control-H, the display will be started without 
apparently disturbing the computation in progress. Similarly, 
typing an S will stop the display. Typing anything else 
followed by control-H will cause a normal interrupt. Similarly, 
if nothing is typed previous to a control-H, the arming function 
returns NIL and a normal interrupt occurs. 

The function disarm of no arguments reverses the effect of arm 
and restores the definition of interruptl . 

Note that since the gctrp feature, p. 10.3, operates by simulating 
a control-H, arm can be used to automate the operation(s) the user 
wishes performed whenever a garbage collection is about to occur, 
i.e. less than N conses away. For example, suppose the user wants 
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the display turned off when there are fewer than 200 conses left 
He would then perform gctrp[200], and arm[F00], where POO was 
defined as: 

( FOO 

(LAMBDA NIL 
(COND 

(CLESSP (GCTRP) 
200) 
(HPSTOP) 
T)))> 
N IL 
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APPENDICES 
Appendix 1 
Converting LISF 1.5 programs to BBN LISP 

Although we have put considerable effort in the design and imple- 
mentation of the BBN LISP system into making it an upwards compa- 
tible extension of LISP 1.5 as implemented on CTSS at MIT or the 
Q-32 at SDC, nevertheless many LISP programs, particular large 
systems, cannot be transferred intact from LISP 1.5 to BBN LISP 
and expect to run. However, the modifications required are 
usually quite trivial once the user is aware of what is necessary 
This appendix is designed to document and call attention to the 
various differences between the two systems, and to facilitate 
this transition. 

The easiest type of incompatibility to handle are functions that 
are defined in LISP 1.5 but not defined in BBN LISP. These are: 



advance 

at t rib 

clearbuff 

common 

cpl 

cset 

csetq 

dash 

digit 

dump 

efface 

endread 

errorl 

evlis 

excise 

flag 

function 

intern 

label 

leftshift 

liter 

max 

min 

mknam 

numob 



onep 

op char 

opdefine 

pause 

plb 

printprop 

punch 

punchdef 

punch lap 

readlap 

recip 

remflag 

remob 

search 

select 

speak 

special 

st art re ad 

tempus-fugit 

traceset 

uncommon 

uncount 

unspeciai 

untraceset 
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The functions advance , clearbuff , dump , endread, errorl , pause , 
plb , punch , punchdef , punchlap , readlap , start read , and temp us - 
fugit relate to input and output, or to the time sharing systems 
themselves. These features are always highly system dependent. 

The functions cpl , dash , digit , intern , liter , mknam , numob , 
opchar , and remob relate to the way LISP 1.5 represents and treats 
atoms. In BBN LISP, there are no character objects; BOFFO also does 

not exist, remob is not necessary because any atom not being used is 
automatically reclaimed by the garbage collector and removed from 
the oblist. If the user's programs perform printname manipulations, 
he will want to use the BBN LISP functions pack and unpack , and 
perhaps chcon , character , nthchar and nchars . 

The functions special , unspecial , common and uncommon relate to 
the LISP 1.5 compiler. Because of the structure of the BBN push- 
down list, it Is unnecessary to make a variable special (or common) 
when it is to be shared by several compiled (or compiled and inter- 
preted) functions. This is taken care of automatically. 

The functions speak and uncount relate to the LISP 1.5 cons counter. 
In BBN LISP, the function cons count gives the number of conses. 
However, getrp , p. 10.3 is somewhat analagous to the LISP 1.5 function 
count , which causes a trap if more than a specified number of conses 
occur. Note: the function count is defined in the BBN LISP system, but 
its value is the count of number of LISP words used by its argument 
which is a LISP S-exDression. 
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The functions cset and csetq do not exist in BBN LISP because 
there are no APVALS; instead set and setq are used at all levels 
to change the binding of a variable. If performed when a variable 
is not locally bound, they will change the top level binding. 

Excise is not defined. Since BBN LISP provides a substantially 
larger number of free words, than LISP 1.5 3 the user should not 
miss it. However, the function flushcode can be used to recover 
space occupied by certain system functions. 

The function traceset and untraceset are not defined. We feel 
that the function b re akin provides this capability and more. 

The function left shift is called lsh in BBN LISP. 

The effects of the function printprop can be achieved by using 
prettydef with an appropriate third argument. 

The function efface is called dremove . There is also a function 
remove which returns the same value but does not destroy the 
original list. 

Function relates to the funarg device in LISP 1.5, which does not 
exist in BBN LISP. 

This leaves the function attrib , evlis , flag , label , max , min, 
onep , opdefine , recip , remflag , search and select which do not 
happen to be implemented. 

The next class of incompatibilities concerns functions that are 
defined in both systems but whose effects are different. The 
functions such as cond , map , map con , map list , prinl , print , and 
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read all give the same results as their LISP 1.5 counterparts 
when given arguments consistent with their LISP 1.5 definitions. 
However, the mapping functions in BBN LISP all permit extra argu- 
ments for various options, and similarly the input-output functions 
permit an extra argument to designate the destination or source of 
the operation. The function cond will return the same value as 
its LISP 1.5 counterpart if given clauses containing only two 
elements, but also permits an arbitrary number of clauses. There- 
fore, these differences should cause no difficulties. 

The predicates and, member , numberp , and or in LISP 1.5 all return 
T or NIL. In BBN LISP, they return a "useful" quantity or NIL. 
When used in a cond as a predicate, the effect is the same. The 
only anomaly the user might encounter would occur if he compared 
the value of a BBN predicate to T, e.g., (EQ (NUMBERP X) T). In 
BBN LISP, numberp[x] is either x or NIL. Thus, one can write 
(COND ((NUMBERP X)) (0)), or even (OR (NUMBERP X) 0), instead of 
(COND ((NUMBERP X) X) (T 0)), as would be required in LISP 1.5. 

The functions that really differ between the two systems are 
a PP lv > eval , load , pack , trace and untrace . Since there is no 
a-list in BBN LISP, apply and eval are functions of two and one 
arguments respectively. The evaluation of variables depends on 
the state of the push-down list. However, the function evala of 
two arguments is provided to emulate the LISP 1.5 function eval 
complete with a-list. 

The function pack in LISP 1.5 takes a character object and add it 
to BOPPO. It is used in the process of creating a new atom. The 
function pack in BBN LISP takes a list of atoms as Its single 
argument and makes a new atom out of them. Thus, pack[x] in 
BBN LISP is equivalent to performing the following operations 
in LISP 1.5: 
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CLEARBUPPO 

NIL 

MAP (list-of-atoms (FUNCTION (LAMBDA (X) 

(MAP (GET X (QUOTE PNAME)) (FUNCTION (LAMBDA (Y) 
(MAP (UNPACK Y) (FUNCTION PACK )))))))) 
NIL 

E (INTERN (MKNAM)) 
new- atom 



The functions trace and untrace are part of the debugging package. 
Their effects are similar to those of the LISP 1.5 functions, but 
in BBN LISP they take an indefinite number of arguments, whereas 
in LISP 1.5, they take a single argument which is a list of func- 
tions. Also the output produced by tracing differs. 

The function load in BBN LISP expects a list of forms for eval ; 
in LISP 1.5 load expects a list of doublets for evalquote . This 
may cause some difficulty initially. However, since most symbolic 
files are created by prettydef , which knows the format for load , 
once the user has made the Initial transition, no further problems 
should occur. Note: one easy way to convert a file from LISP 1.5 
format to BBN format is to perform: 

READFILE(FOO file) 

F00 

SETQ(FOO (MAPLIST F00 (FUNCTION (LAMBDA (X) 

(LIST (QUOTE APPLY) (LIST (QUOTE QUOTE) (CAR X)) 
(LIST (QUOTE QUOTE) (CADR X))))) 
(FUNCTION CDDR))) 
big-hairy-list 
WRITEFILE(FOO new- file) 
F00 

In addition to the differences discussed above, the user will 
experience difficulty if his LISP 1.5 programs make assumptions 
about the internal representation of atoms, function definitions, 
etc. To review these differences briefly: 
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In BBN LISP, car of an atom is always its top level binding, edr 
of an atom is always its property list. Consistent with this, car 
of a number is always the number itself, cdr of a number is always 
NIL. If the user's LISP 1.5 programs make assumptions about car 
of an atom, they will not work in BBN LISP. 

In BBN LISP, function definitions are not kept on the property 
list, but in a special cell which can only be accessed by the 
functions getd and putd . If the user's LISP 1.5 program assumes 
that the function definitions are on the property list, i.e., 
uses DEFLIST instead of DEFINE or DEFINEQ, it will not work. 

The FEXPR's of LISP 1.5 are subdivided into FEXPR's and FEXPR*'s 
in LISP 1.5. Similarly, EXPR's in LISP 1.5 are subdivided into 
EXPR's and EXPR*'s. The type in each case is indicated by either 
LAMBDA or NLAMBDA, and the use of an atomic or non-atomic argument 
list. Trying to define an FEXPR in BBN LISP by using DEFLIST will 
not work. 

There are no properties APVAL or PNAME on the property list of 
atoms in BBN LISP. 

There is no a-list in BBN LISP. 

Finally, the following two items should be noted: there are 
separate fixed and floating point arithmetic functions in BBN LISP; 
and atoms may not be split at column 72 in BBN LISP. A carriage 
return in BBN LISP is a separator character and will split an 
atom. If your LISP 1.5 file contained atoms split at column 72 
and carried over in column 1, it will not read in correctly, i.e., 
you will get two atoms instead of one whenever an atom was split. 
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Appendix 2 

The BBN LISP Interpreter 

The flow, chart presented below describes the operation of the 
BBN LISP interpreter, and corresponds to the m-expression 
definition of the LISP 1.5 interpreter to be found on pp. 70-71 
of the LISP 1.5 manual, McCarthy, 1966. Note that CAR of a form 
must identify a function, as with LISP 1 . 5 but the procedure the 
interpreter uses to obtain this function can be fairly compli- 
cated. The most ccmmon case occurs when CAR of the form is an 
atom. The function is then properly identified if its function 
cell contains: 

(a) an S-expression of the form (LAMBDA ...) or (NLAMBDA ...) or 

(b) a number which is the address of a SUBR or a block of compiled 
code . 

Otherwise, if the function cell contains NIL, the atom is evalu- 
ated, and its value treated as if it were CAR of the original 
form. (This is the way functional arguments work.) If the evalu- 
ation of the atom produced NIL or T, or if the atom is unbound, 
the form is considered faulty, and faulteva l is called as des- 
cribed in section 15. 

If the function cell contains an expression other than NIL, this 
expression is evaluated and treated as though it were car of the 
original form, etc. In other words, it is possible to put the 
name of a function, or a form which co mputes the name of a 
function, in either the function cell or the value cell of an 
atom, and then to use the atom as a function. 
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YES 


CALL 
EXPR 








YES 


CALL 
FEXPR 





ENTER EVAL WITH FORM 




YES 



SET D = 
CONTENTS OF 

DEFINITION CELL. 
PUT C ON PDL 

AS FUNCTION NAME 



SET 
C=-D 




YES 



RETURN 
BINDING 



CONSTRUCT 
(FAULTEVAL-FORM) 



I 



RE-ENTER EVAL 



YES 



CALL SUBR OR 
COMPILED CODE 



SET D = 
BINDING OF C 




NIL,T,NOBIND 



OTHER 



iote: Variables c anu u are for description only; they are 
not actually bound an regular variables. 
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Appendix 3 
Control Characters 

Several control teletype characters are available to the user for 
communicating directly to LISP, e.g. to abort or interrupt a com- 
putation, tell LISP to start or stop listening to the teletype, 
change the printlevel, etc. This section summarizes the function 
of these characters and references the appropriate section of the 
manual where a more complete description may be obtained. 



1. Rub out Clears tty input and output buffers. 

For example, the user would use rub- 
out if he had "typed ahead" of the 
program, (typed while the program 
was computing but not listening), 
and wanted to eliminate all unpro- 
cessed input. Also this action may 
be useful when the program is pro- 
ducing a large quantity of tty out- 
put and the user wishes to skip some 

but not all of it. Ooeration of rubout 
when the program is doing output to 
tty will cause 30-40 characters to 
be skipped, but allow output to 
continue. 

Rubout also terminates and restarts the 
tty input fork. If LISP has stopped 
listening because of a control-S, or 
its buffer is full, or some other 
reason, rubout will start it listen- 
ing again. 

Note, closely spaced repeated rubouts. 
will terminate LISP and cause a return 
to the exec. This type of return may 
make it impossible to continue the 
LISP . It should only be used if con- 
trol-C and/or logout absolutely fail 
to work. 
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2. Control-R 



Generates an error, type 1, p. 15.30. 



3. Control-C 



4. Control-H 



Causes immediate return to evalquote 
top level (after garbage collection 
if one is in progress). 

At next function call, computation 
is interrupted and breakl is ca iled, 
p. 15.25 or other special action 
explicitly determined by user. (n. 22.2) 

Note if you are in a compiled function 
that does not call any other functions, 
the control-H will not take effect 
until the function is exited. 



5. Control-T 



Print Time . Causes an immediate 
printout of the total execution time 
(in clock ticks) for the job, (even 
during garbage collections), i.e. 
clock[2], (p. 14.22). A series of 
such printouts should show increasing 
numbers if the program is using any 
CPU time. Of course, the program is 
not using CPU time if it is waiting 
for input. This information may 
serve to help the user determine if 
his LISP and/or the time sharing sys- 
tem has crashed. 



6. Control-F 



Set Free Words , 
by a decimal numb 
period will immed 
to be set to the 
even if a garbage 
already started, 
lector uses the s 
about 3/4 ths of 
if control-F is t 
it will not take 
next garbage coll 



Control-F followed 
er followed by a 
iately cause minf s 
indicated number, 
collection has 
The garbage col- 
etting of minfs 
the way through, so 
yped after this time, 
effect until the 
ection (p. 10.3) 
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7. Control-P 



Set print level . Control-P followed 
by a decimal number followed by an 
exclamation point will change the 
printlevel to that number, i.e. it 
is the same as calling printlevel 
except that it may be performed 
while output is actually in progress. 
Control-P followed by a decimal num- 
ber followed by a period will change 
printlevel for the current S-exoression 
only. (14.4-3.4.5) 



8. Control-S 



Terminates LISP teletype input fork, 
thus preventing LISP from gobbling 
innut and servicing other control 
character requests. Can be reversed 
by rubout - see 1 above. Normally 
this option would only be used if the 
user wished to type input to be pro- 
cessed by the time sharing system 
executive while he was still inside 
of LISP, e.g. he had a compilation 
going and wanted to leave instructions 
for exiting from the system. He could 
do this by typing L0G0UTO, control-S, 
and EX I. 



9. Control-A,Q 



Control characters for READ, see p. 2.1 
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Appendix 4 

Index to Variables 

Following is a list of those atoms in the basic system which 
are initialized with top level values. Atoms that may be of 
interest to the user are given a brief explanation and a page 
reference, where applicable. Atoms which are internal and should 
normally not be of interest to the user, e.g. list of instruction 
codes, various compiler flags, etc. are listed to avoid inad- 
vertent clobbering by the user. 



In addition to the atoms with top level bindings, the variables 
LAMBDA, NLAMBDA, and lower case single character atoms a,b, . ..z 
which are printed as %k 9 %B ... %Z are used by the interpreter 
(see p. 12.4) and the user should not use them in his functions. 



General 

T 

NIL 

P 

NOBIND 
STATCELLS 



Description and/or Value 

T 

NIL 

NIL 

T 

means atom bar; no top level bind- 
ing, see p. 15.22 

list of dotted pairs of form 
(name . number), e.g. (WRAPAROUNDS . 
199) where name is a statistic kept 
by the system, and number the locat- 
ion of the cell containing that 
statistic, e.g. openr[l$>9] gives 
number of wraparounds. Used Dy timex, 
P. 22.5-7. 
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DFNFLG 



HELPDEPTH, HELPFLAG 



NHERRORS 



ESGAG 

FLUSHPOINTS 

BPSPACE 

CLITRLIST 
ADVISEDFNS 

SYSTEMS 

ICP, CP, IPP, PP 



used by define , defineq, and unsaveuef 
to determine whether function definit- 
ions are saved on property lists, p. 8.3 

used by error handling routiners to 
determine whether or not to call breakl , 
p. 15.23, 15.25, 15.26 

list of non-helpable errors, i.e. 
those error types for which breaks do 
not occur, initialized to (0 1 18), 
see p. 15.30, 15.31, 15.35. 

controls backtrace printout during 
unwinding, p. 15.3^, 15.35. 

list of form (name . location) for use 
by flushcode , p. 22.8 

list of "holes" in user's binary pro- 
gram space, p. 22.8. 

used by garbage collector 

list of functions that have bee advised, 
p. 19.7 

used by subsys , p. 17.10 
push-down handles, p. 12.11 



Comoiler 



OPENFNS 



LAPFLG, STRF, SVFLG, NLAMA, 
NLAML, LCFIL, LSTFIL 

SYSNIL, SYST, SYSTAT, SYSNUM, 
SYSINT, TOPBPS, FREELW, CTEMP, 
INTZRO, SPCELL, PPPTR, FPPTR 

PREDLIST, PREDS1, PMAC, SYS, 
SYSFNS, SYSNOTFNS, LAMS 



list of functions to be compiled 
open, p. 16.12. 

answers to compset questions p. 16. 6-9 
p. 16.28 

internal to compiler. 
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Break 
BROKENPNS 

BRKEVQFLG 

BREAKMACROS 
BREAKI 

CHNGNM 
NBREAKS 



list of functions that are broken, 
p. 15.13, 15.14, 15.18 

used by breakl to determine whether 
user is talking to evalauote or eval 
when inside a break p. 15.10. 

P. 15.8 

number of spaces indented on each 
break, initially set to 3 



p. 

bound to number of recursive breaks, 
at top level. 



NOBREAKS 



list of functions ignored by breakin 
search, p. 15.17 



CHNGNM, VVNLAST, NOBREAKIN 



internal 



Editor 

EDITMACROS 

MAXLEVEL 

SUPEREDITFLG 



p. 9.17 

controls depth of find command, p. 9.7, 
initialized to 100 

p. 9.26, 9.27 



EDITMAKROS, EDITOPS, EDRPTCNT, internal to editor 
PINDPLAG 



Display 

DISPLAYMACROS 

CONVERTERLST 



XORG, YORG, RORG, LORG, 
SCALEX, SCALEY, CHARSIZE 



p. 18.6 

list of D-A converters to be used, 
p. 18.2 

p. 18.11 
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HANDLE 
MASKTABLE 
TRNPTS, TRSPACING 



p. 18.16 

masks for characters, p. 18.14 

used by dtree p. 18.8 



ASSIGNFLG, CHARTABLE, CHARRAY, Internal to disolay 
CA , PNO 



Breakdown 



BREAKDOWNPORM 



p. 22.4 



STATFACTORS , CTTAB, Internal breakdown 

MORESTATCELLS, CWTAB, BKDWNFN, 
BKDWNFMS, BDLST, BDPTR, BRKOVHD, 
BRKTERP, BRKLABEL 



Print structure 

YESFNS, NOPNS, QUOTEFNS, 
NOTRACE, PRDEPTH 

FIRSTLOC, LASTLOC 



p. 21.3, 21.4 
internal 



Edlta 

USERSYMS, SYMLST 

EDITBRK, OPCODES 

FLIP 



p. 9.46 
Internal 



FLIPBRKSAVE, FLIPBRK, A" (NIL)", D"(NIL)", "(T) If , FLIPMODE, LASTREAD, 
UNRD, NORMBRK, SEPRS, SAVELST, $TRAN, TRAC, RTRAC, FLIPDEFAULT , INUSE, 
NOCONS, SAFE2USE see FLIP Manual 
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DWIM 



CFACT1, CFACT2, DELAYTIME 

USERWORDS 

LASTWORD 

REDLIGHT, GREENLIGHT, UBA, UDF 

MODELST 

FAULTDEPTH 

FILELST, FILESPLST, 

SPELLINGS]., SPELLINGS2, 
SPELLINGS3, SPELL1, SPELL2, 
SPELL3, FIX8, FIX9, FIXT, 
OPTIONSPNS 



Spelling correction, p. 20.11 

p. 20.13, 20.15 

p. 20.15 

modes, p. 20.13, 20.14 

list of mode definitions, p. 20.13 

nofix , p. 20.16 

used by newfiles , p. 20.14 

internal 



PRETTYPRINT 



FIRSTCOL, LASTCOL, ABBREVLST 



u 



sed by comment feature, p. 14.15 



MISCELLANEOUS 

MAPRINTL, MAPRINTJ, MAPRINTI , miscellaneous internal 
APN, PATV, PFPA, PENT, PIPV, 
PRETN, PCLL, PMKN, PFVE, PCONS, 
PCDR, PCAR, SINTABLE 
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Appendix 5 

Properties and property lists 

The following properties are used by system functions: 

OPD, MACRO, COREVAL, CTYPE, CROPS compiler 

CLITRLIST garbage collector 

EXPR, CODE savedef, unsavedef 

BROKEN, BRO KEN-IN, NAMESCHANGED, break 
ALIAS 

ADVISED, ADVICE advise 

The following atoms have their property lists initialized to 
other than NIL; the user should avoid clobbering them; i.e. use 
DEPLIST, PUT and REMPROP, not RPLACD, for modifying property lists. 

PROPERTY OPD: 

C SKD LDE STE BAC ROV OVT NOD FSB WCI WCH GC I PSTR PLAI due 
AOC STP LOP TCI TCO CTRL BIO WIO CIO EXU NOP LCY RCY S*R 
SKN SK8 SKA SrtM 3RR 8RM 8RX CLAB CXA C3A CAX CLX SUB MIN 
ADM EAX STX 8SS MUL XAB 01 V PFF\J PMFN XXB CBX CAXB CLLXA 
CLLX LDN PSA I NSTA BR J SKE ARGSUB CNA SARGN ARGN VS T 1 CSP1 
CLA XMA LDA LOB STB SXMA S TA SKG MPY 0\J0 NEG EOR MRG E TR 
SWAP FUNBOX FEiMBOX FDV FMP FAD CLLA NSTT BXC CAB CLB VAL 
LOT STN STT LDV JUMP STV LOX CLL LQT RET SET IX BUI BII BJF 
B IF BR2 BR1 BNLST BLST 8NS BIS BtMI 8NA BA 3NAP BAP BN.M BiM 
BiME MSAI BRS BE LFV 31 DIVIDE ADD RSH LRSH LSH BSS1 EN80X 
UNBOX CONSCLL PATV PENT PIPV PRETN PCLL PMrfvj PFVE PCO.MS 
PCDR PCAR) 
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PROPERTY MACRO: 



C // AC IFPRED MATCH4 FAILURE EVALPRED TRANSLATE3 KWOTE ASSEMBLE 
ZEROP SUB1 SETA NLSETQ MINUSP MAP EVQ ERSETQ ELT DIFFERENCE 
ABS RSH LRSH LSH FRPLAC NLISTP MEMB ADD1 .MEQ MAPC * VAG 
S ETARG LOC LIST ARG) 



PROPERTY COREVAL: 



(ATVAL FPDLA ENTER IPV XCLL ENBOX UNBOX CONSCLL CDRCLL CARCLL 
CP PP IPP ICP FPPTR PPPTR SPCELL INTZRO CTEMP FREELW T0P8PS 
SYSINT SYSNUM SYSTAT SYST SYSNIL PATV PENT PIPV PRETN PCLL 
PMKN PFVE PCONS PCOR PCAR RETURN) 



PROPERTY CTYPE: 

CLISTP LESSP DIVIDE ARRAYP CDDDDR CDDDAR CDDAAR CDADDR CDADAR 
CDAADR CDAAAR CADDDR CADDAR CADADR CADAAR CAADDR CAADAR 
CAAADR CAAAAR FIXP CDDADR TIMES REMAINDER QUOTIENT PLUS 
OR NUMBERP NULL NOT MINUS LOGXOR LOGOR LOGAND GREATERP FTIMES 
F QUOTIENT FPLUS FMINUS FLOATP EQ CDDR CDDDR CDDAR CDAR CDADR 
CDAAR CADR CADDR CADAR CAAR CAADR CAAAR ATOM AND) 



PROPERTY CROPS: 



C CDDDDR CDDDAR CDDAAR CDADDR CDADAR CDAADR CDAAAR CADDDR 
CADDAR CADADR CADAAR CAADDR CAADAR CAAADR CAAAAR CDDADR 
CDDR CDDDR CDDAR CDAR CDADR CDAAR CADR CADDR CADAR CAAR 
CAADR CAAAR) 



In addition, the atom CLITRLIST has a property value LITERALS 
which is used by the garbage collector, and the atoms HELP-IN- 
UNSAVED1, PRINT-IN-PRETTYPRINT1, ERROR-IN-EDITP, ERRORSET-IN- 
EDITE, MAKEFILE, BREAKO, EDITP, EDITV, EDITF, RPAQQ, DEFINEQ, 
LOAD, EDITE ^ PRETTYPRINT1 , and UNSAVEDl have property lists used 
by DWIM , see p. 20.13. 
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INDEX TO FUNCTIONS * 



NOTE: ALL FUNCTIONS ARE LAMBDA, SPREAD UNLESS 
INDICATED OTHERWISE USING THE CODE 
NL=NLAMBDA, *=NOSPREAD 

NAMES IN PARENTHESES, E.G. (DWIM), (ADVISE), 
REFER TO FLUSHPOINTS. 



NAME OF 
FUNCTION 



DESCRIPTION 
PAGE 



ABS[X] 13.3 

ADD[X,Y,Z] 7.3 

ADD1CX] , 13,1 

ADDSPELL[X,FLG3 (DWIM) 20,15 

ADVISE[NAME, WHEN, WHERE, WHAT] (ADVISE) , 19.6 

ADVISEDUMPCX] (ADVISE) 19.8 

ALLCALLS[FN,TR;i (PRINTSTRUCTURE) 21.8 

ALLOC ATE [N,L ] , 10.5 

ANDC--1NL* 5.10 

ANTILOG t X ] . , , , . 13.5 

APPEND [ X, Y 3 6,1 

APPLY [U,V] 8.5 

ARGCU] ., 8.6 

ARGLISTCX3 8.5 

ARMCFN3 22. 1U 

ARRAY [N,P,W] ., 10.6 

ARRAYPCX] , ., 5.9,10.7 

* FOR INDEX TO VARIABLES SEE APPENDIX 3, P. 23.9 
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NAME OF DESCRIPTION 

FUNCTION PAGE 

ARRAYSIZEU3 ............ 10.7 

ASSEMBLE[NOT A FUNCTION] (COMPILER) ... 16.16 

ASSIGNDCDEVj (FORK) . 17.12 

ASSlGNPtPNOj (FORK) .coo,......,, 17.12 

ASSOC[XSAS,YSAS] 7,3 

ATOMCU] , .... 5.9 

ATOMGCCFLG] ... 10.3 

ATTACH [X, Y ] 6.2 

BACKTRACES, V] (PDL) 12.8 

BAKTRACE[N] (PDL) 12.8 

BI[M,N,X] (EDIT) 6.7 

BO[N,X] (EDIT) c 6,7 

BREAK[X]NL* (BREAK) 15,1,14 

BREAK0[FN,WHEN,COMS P FILE] (BREAK) ..... 15.13-14 

BREAK1CBRKEXP P BRKWHEN,BRKFN,BRKC0MS,BRKFILE]NL 

(BREAK) ,... , 15,5-12 

BREAKD0WN[X3NL* (BREAKDOWN) 22.3 

BRE AKIN C FN, WHERE, WHEN, COMS, FILE ] NL 

(BREAK) 15.1,14 

BREAKNARGS[N] (BREAK) 15.24 

BRS[N,A,B,Xj (MSC) 17.20 

CADVICECFNS] (ADVISE) . 19.10 

CALLS[FN] (PRINTSTRUCTURE) ,, 21.8 

CAR, CDR, ETC.[U] ..... 5.1 
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NAME OF DESCRIPTION 

FUNCTION PAGE 

CHANGENAME[FN,FROM,TO] (BREAK) 15.19 

CHANGEPROP[X,PROP1 # PROP2] (MSC) 7.1 

CHARACTERS] 10.2 

CHCON[U,V] 10,2 

CLEARBUF[U ] . . . 1 U . 10 

CLEARSTAT[ ] 10.6 

CLOCK [U] 22.2 

CLOSEFCU] 14.2 

CLOSERCU,V] 10. U 

COMPILECX] (COMPILER) , 16.3 

COMPILE2[FN,DEF] (COMPILER) . 16.5 

COND[--]NL* 4.3,5.4 

CONSCU/V] 5.2 

CONS'COUHTCU] 5.3 

CONSPAGECU] , 5.2 

CONTRACTU] , 16.15 

CONTROL [U,V ] 1U.10 

COP Y [ X ] ........ 6 . 3 

COPYFILE[FRQM,TO] 14.12 

COSINECTHETA] (DISPLAY) 13.6 

COUNTCL] 6,6 

D ATEC ] ..... 22.2 
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NAME OF DESCRIPTION 

FUNCTION PAGE 

DATOM[ATOM,PRIN2,X,Y] (DISPLAY) 18.13 

DCIRCLE[RADIUS,DTHETA,A,M] (DISPLAY) .. 18,7 

DDTC3 . ., .. 17.9 

DEFINE [X ] , , . . 8.2 

DEFINEQ[X]NL* 8.U 

DEFLIST[L,IND] ....... 7.2 

DELFILECFILE] 14.12 

DIFFERENCE [X,Y 3 , .. 13.1 

DISARMC3 (BREAKDOWN) 22. 1U 

DISCHARCC] (DISPLAY) 18.14 

DISPLAYCFIGj (DISPLAY) 18.17 

DISPLISTCFIG, PLACE, HANDLE] (DISPLAY) .. 18.15 

DISPLIST1[FIG,X,Y # SCALEX*SCALEY] 

(DISPLAY) 18.15 

DIVIDE[X # Y] 13.2 

DLINE[X,Y,DX,DY,N,A,M, SHIFT] (DISPLAY) 18.7 

DPRIN1[X,PRIN2] (DISPLAY) , 18.13 

DPRIN2CX] (DISPLAY) 18,13 

DPRINTCX] (DISPLAY) 18.13 

DREMOVE[X,Y] 6.13 

DREVERSECX] 6.3 

DRUN[HANDL,NT] (DISPLAY) 18.16 

DS[S] (DISPLAY) 18.8 
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NAME OP DESCRIPTION 

FUNCTION PAGE 

DSPACESCN] (DISPLAY) .. 18.13 

DSUBST[X,Y,Z] 6, 4 

DTERPRIC] (DISPLAY) .... 18.13 

DTREECTREE] (DISPLAY) 18,8 

DVECTOR[X0,Y0,X1,Y1,N,A,M] (DISPLAY) .. 18.7 

DWIMCX] (DWIM) 20.5 

E[XEEEE]NL* , 8.5 

EDITA[EDITARRY,COMS] (EDlTA) .......... 9.41-49 

EDITCOMCC] (EDIT) ' 9.19,20 

EDITCOMSCC] (EDIT) 9.20 

EDITDEFAULTCEDITX] (EDIT) 9.21 

EDITE[X,OPS] (EDIT) 9.18,20 

EDITF[X]NL* (EDIT) 9.18 

EDITL[L,0PS3 (EDIT) .. 9.18,20 

EDITNTH[X,N] (EDIT) 6.7 

EDITP[X]NL* (EDIT) 9.18 

EDITV[EDITVX]NL* (EDIT) ............... 9.18 

ELT[A,N] 10.7 

ENDFILECY] (PRETTY) 14.16 

EQ[U,V] 5,9 

EQP[U,V] 5,10 

E Q U A L [ X , Y ] 5.10 
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NAME OF DESCRIPTION 

FUNCTION PAGE 

ERRORCU] .15.33 

ERRORM[U,V] 15.32 

ERRORNC] 15.32 

ERRORSET[ERSETX,ERSETFLG] 15.23,26,33 

ERRORX[ERRORXN,ERRORXFLG3 , 15,35 

ERSETQ[ERSETX]NL , 15.34 

ESGAGCX] 15.34 

EVALCU] 8.4 

EVALA[FEVAL,AEVAL] 8.5 

EVALR[U,V] 8.5 

EVALV[U,V] 12,7 

EVERY[EVERYX,EVERYF] (MSC) 11, 4 

EVQCX] (COMPILER) 16. 1U 

EXPANDU] 16.15 

EXPANDCOMP[MF,A] (COMPILER) 16.12 

EXPT[X,Y] 13.5 

FAULTEVALCFAULTX]* 15.22,23 

FDDTC] . , , 17.10 

FGTP[U,V] , 13. U 

FILETYPECU] 14.12 

FIRSTFNLFN] ( PRINTSTRUCTURB ) 21.7 

FIXCU] 13.U 
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NAME OF DESCRIPTION 

FUNCTION PAGE 

FIXPCX] 13.4 

FLOAT[U] 13. U 

FLO ATP [ U ] . . 13.4 

FLTFMTC U ] , . . . , 1 3 . U 

FLUSHCODE[FROM,TO,FLG] 22.8 

FMINUS[U] 13. U 

FNTYP[X] ., 8.2 

FOLLOW C FN , FLG ] . . 21.9 

FORKINITC] (FORK) # 17.13 

FPLUSC--]* ., 13.5 

FQUOTIENTCU# V ] 13.5 

FREEVARSCFN] ( PRINTSTRUCTURE ) 21.8 

FTIMESC--]* 13.5 

FUNCTION [-- ] NL* . . . 11,1 

GCGAG[U] , 10. U 

GCTRPCU] ...... 10.3 

GENSYMC] . . 10.2 

GET[X,Y3 ,, 7.2 

GETDCU] 8.1 

GETL[X,X] 7.2 

GETP[X,Y] 7.2 

GINFN [ U ] 14.12 
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NAME OF DESCRIPTION 

FUNCTION PAGE 

GOO-ONL* , 5,7 

GOUTFN[U] ,., , , 14.12 

GREATERP[U,V] 13.2 

GROUP [LST] ,. 22.13 

HELP [HELPX, HELP Y] , , 15,33 

HPRUN[AP,LC,NP,ITER,PNO] (FORK) 17.19 

HPSTARTCST,NT # LC#LD] (FORK) 17.17 

HPSTOP[] (FORK) 17.18 

HPTABLE[M,N3 (DISPLAY) 17,19 

HPTESTC3 (FORK) .. 17.18 

HPWAITC3 (FORK) ,, 17.18 

INFILE[U,V] . , 14.2 

INPUT [U] , 14.1 

INTERRUPT [ INTERRUPT ARGS]* , 15.24 

INTERSECTION [ X, Y ] . 5,11 

LAMBDACNOT A FUNCTION] 4.. 1-4 

LASTCX ] , 6.6 

LASTFN[FN] ( PRINTSTRUCTURE ) 21.8 

LCONC[X,P] 6.2 

LDIFF[X,Y,Z'J 6.7 

LENGTHCX] ., 6.6 

LESSP£X,Y] 13.2 
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NAME OF DESCRIPTION 

FUNCTION PAGE 

LI[N,X] (EDIT) 6.7 

LINELENGTHCU] . .. ., 14. 11 

LISTC^-]* . 6.1 

LISTFILE[FILES]NL* (MSC) 1U.21 

LISTP[X] 5.9 

LO[N,X] (EDIT) 6.7 

LOAD[LOADF,SVFLG,LOADFLG] 14.13 

LOADCLCFILESINL* (SAVECL) 22.12 

LOCCU] • . 10.4 

LOGCX] , 13.5 

LOGAND[— •]* 13.2 

LOGORC--]* 13.2 

LOGOUT[U] 10. U 

LOGXORC--]* , 13,2 

LRSH[X,N] 13.3 

LSH[X,N] 13.3 

LSUBLIS[X,Y] (MSC) 6.5 

MAKEFILE[FL,FLG] (MSC) 14.21 

MAKELIST[N,M] (MSC) 6.8 

MAKETABLE[PLACE,SIZE] (FORK) .......... 17.14 

MAPCMAPX, MAPFN 1 , MAPFN21 . 11.1 

MAP2C[MAPX,MAPY,MAPFN1,MAPFN2] ........ 11.3 
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NAME OF DESCRIPTION 

FUNCTION PAGE 

MAP2CAR[MAPX,MAPY,MAPFN1,MAPFN2] 

. , 11,3 

MAPA[MAPARY,MAPFN1,MAPFN2,MAPN] 

(MSC) 11.3 

MAPCCMAPX, MAPFN 1 ,MAPFN2] . . . . . 11.2 

MAPCAR[MAPX,MAPFN1,MAPFN2] 11,2 

MAPCON[MAPX#MAPFN1,MAPFN2] 11.3 

MAPCONC[MAPX,MAPFN1,MAPFN2] . .... 11.2 

MAPDL[MPDLFN,MPDLN] (BREAK) 12.9 

MAPLISTCMAPX^MAPFN1 # MAPFN2] ..... 11.2 

MAPRINT[LST,FL,L,R,S,PFN#C1 (MSC) ..... 11.4 

MEMB[X,Y] 5.11 

MEMBER [X,Y] . , 5.11 

MINFS [U] 10 . U 

MINUS [U3 13,1 

MINUSPCX] . ... 13.2 

MISSPELLED?CX,FN,SPLST] (DWIM) ., 20.15 

MOVD[FROM,TO,COPYFLG] (MSC) ........... 8.1 

MOVEFIGCMVFGJNL* (DISPLAY) .. 18.10 

MO VEP0INTS[ MATRIX, DX, DY, HANDL. REL, NP> FROM] 

( FORK ) 18.22 

NARGSCX3 . , .. ., 8.5 

NCHARSCU] 10.1 

NCONC [U, V ] , 6.1 

NCONC1[LST,X] (MSC) 6.1 
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NAME OF DESCRIPTION 

FUNCTION PAGE 

NEQ[X,Y] 5,10 

NEWFILES[FLG] (DWIM) 20. 14 

NILLC] . , 5.10 

NLAMBDACNOT A FUNCTION] 4.1-4 

NLIST[XNLIST]NL* 6,1 

NLISTPCX] 5.9 

NLSETQ[NLSETX]NL 15.34 

N0FIX[] (DWIM) 20.16 

NOTCU] 5,11 

NTH[X,N] 6.6 

NTHCHAR[U,VJ 10.1 

NTHFN[U,V] 12.7 

NTHFNBACKCU] , 12,7 

N U L L [ U ] 5.10 

NUMBERP[U] 13.2 

OBLISTC] ., 10.2 

0PENP[U] 14.2 

OPENRCU] 10.4 

OR[--]NL* 5,11 

OUTFILE[U,V] 14,2 

OUTPUTCU] , 14.1 

PACK[U] 10. 1 
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NAME OF DESCRIPTION 

FUNCTION PAGE 

PLOTARHAY[AP,DX,DY,SCLX,SCLY,VERT,HANDL,REL,NP] 

( FORK ) 18.21 

PLUSC--]* . . 13.1 

POSITION [U] . 14.11 

PRETTYDEFCPRTYX,PRTYY f PRTYL] (PRETTY) , 14.16-20 

PRETTYPRINTCL] (PRETTY) 14.15 

PRIN1[U#V] .. 14.3 

PRIN2[U,V] 14.3 

PRIN3[U,V] 1U.U 

PRINT[U,V] 14. U 

PRINTDATEC] (PRETTY) 14.21 

PRINTDEF[E] (PRETTY) 14.16 

PRINTFNSCX] (PRETTY) 14.21 

PRINTLEVELCU] 14,4 

PRINTSTRUCTURE[FN,FILE] ( PRINTSTRUCTURE ) 21.6 

PROG [ -- ]NL* 5.7 

PROG1[U,V] , 5.6 

PROG2[U,V] ., , 5.6 

PROGN[--]NL* 5.6 

PROGN[ IMPLICIT 3 NL* 4.3-4 

PROP[X,Y,U] 7.1 

PUT[X,Y,Z] 7.1 

PUTD[U,V] 8,1 
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NAME OF DESCRIPTION 

FUNCTION PAGE 

PUTDQ[X,Y]NL 8.1 

QUITCU] 15,34 

QUOTE [ --]NL* 5.3 

QUOTIENT CU , V ] . . . 13.1 

RADIX [U,V] , , 14,10 

RAND[M,N] (MSC) .. 13.3 

RATESTCU] 14,9 

RATOM[U] 1U.7 

RATOMS[A,FN] 14.7 

RBIN[U] 14.12 

RCOMPILBC] (COMPILER) 16.4 

RDFKCADDRESS] (FORK) 17.16 

RDFLX[X3 14.6 

READCU] ..." 14,6 

RE ADC [U] , , 14.9 

READFILE[X,FILE] (MSC) 14.14 

READFORK[AP,INCR,HANDL,REL,NP] (FORK) . 17.16 

READP[] . 14.11 

READVISECNAME] (ADVISE) 19.9 

RECLAIM [U ] 10,2 

RECOMPILE [PRETTYFILE,COMPlLEDFILE,FNS] 

(COMPILER ) 16.3 

REMAINDER [U,V ] 13.2 
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NAME OF DESCRIPTION 

FUNCTION PAGE 

REMOVE[A,X] 6.3 

FEMPROP[X,n 7,1 

RENAME [U,V,W] 12.7 

RENAMEFILE[0LD,NEW] (MSC) .. 14.12 

RESET [] . .... . . 15. 3U 

RETFROM[U # V3 • • 12.8 

RETURNCU] 5.8 

REVERSECX] .. , 6.3 

BI[M,N,X] (EDIT) 6.7 

RO[N,X] (EDIT) 6.7 

RPLACA[U,V] 5.3 

RPLACD[U f V] 5.3 

RPTCRPTN, RPTF] 5.7 

RSH[X,N] 13.3 

RTFRM[RTFN,RTFORM,RTN]NI, (DWlM) ., 12.8 

SASSOC[XSAS,YSAS,USAS] 7.3 

SAVECL[LST,FILE,IDENT] (SAVECL) .. 22.10 

SAVEDEFCX] 8.3 

SEARCHPDL[SRCHFN # SRCHM3 (DWlM) ,, 12.10 

SELECTQ[SELCQ]NL* . . . 5.5 

SET[U,V] 5.8 

SETACA,N,V] 10.7 
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NAME OF DESCRIPTION 

FUNCTION PAGE 



SETARGCU,V] 8.6 

SETBRKO-] * 1 4 . 7 

SETBRKCCX]NL* 14.8 

SETQ[--]NL* 5.8 

SETQQ[XSET,YSET]NL 5.8 

SETSEPRC--]* 14,7 

SETSEPRC[X]NL* , 14,8 

SETV[U,V,W] , 12.7 

SINECTHETA] (DISPLAY) ., 13.6 

SOME[SOMEX,SOMEF] (MSC) 11.4 

SPACES[U,V] 14.4 

START[] (DISPLAY) ..,.,.. 18.2 

START1CJ (DISPLAY) 18.2 

STATISTICS [3 10.5 

STFK[ADDRESS,X] (FORK) ,, 17.16 

STORAGECF] ., 10.6 

STOREFORK[AP#INCR,HANDL,REL,Np] 

(FORK) 17.15 

STOREPOlNTS[AP,DX,DY,SCLX,SCLY,HANDL,REL,NP] 

( FORK ) . . . 18.19 

SUB1CX] 13,1. 

SUBLIS[A,Y] , , ,, . ... 6.4 

SUBPAIRCN,V,L,FL] 6.6 

SUBST[X,Y,Z] 6.3 
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NAME OF DESCRIPTION 

FUNCTION PAGE 

SUBS YS[ NAME, FILE 1,FILE2] . , 17.10 

SYSGET[U] . ,, ......... 2.1 

SYSINCU] 1U.11 

SYSOUT[U] 1U.11 

TAB[P0S,MINSPACES,FILE] (PRETTY) ...... 14.21 

TCOMPLCL] (COMPILER) ., 16.4 

TCONC[X#P] . , .. . , 6.2 

TERPRI[U] . , 14.4 

TICKPSU . 22.2 

TIME[X,N,G]NL . , 22. 1 

TIMES [--]* , , 13.1 

TIMEX[L,QT,N] (BREAKDOWN) 22.5 

TRACE[X]NL* (BREAK) .. 15.1,15 

TREEPRINT[X#N] ( PRINTSTRUCTURE ) ....... 21.7 

UNADVISE[X]NL* (ADVISE) 19.8 

UNASSIGN[] (FORK) 17.12 

UNBREAK[X]NL* (BREAK) 15.18" 

UNBREAK0CX] (BREAK) 15.18 

UNBREAKINCFN] (BREAK) 15.19 

UNION [X,Y] 5.11 

UNPACK [U] t , ., 10.1 

UNREADCCU # VJ .. 14.9 
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NAME OF DESCRIPTION 

FUNCTION PAGE 

UNSAVEDEF[X#TYP] 8,3 

UTILITYCFL] (MSC) 17.10 

VAG[U] 10.5 

VALVCX,FN,N]NL (BREAK) 15.20 

VARIABLES [ U 3 12.7 

VARSCFN] (PRINTSTRUCTURE) 21,8 

VIRGINFN[FN»FLG] (BREAK) 15,19 

WBINCUjV] ,.,.. 14.12 

WRITEFILE[X,FILE] (MSC) ... 14.14 

XCRC] (MSC) . 14.4 

ZEROPCX] 13.2 



